Webhook Management

• Creating or updating a webhook subscription
  • Endpoint
  • Available methods
  • Query parameters
  • Query format
  • Response format
• Listing webhook subscriptions
  • Endpoint
  • Available methods
  • Query parameters
  • Response format
• Deleting a webhook subscription
  • Endpoint
  • Available methods
  • Query parameters
  • Response format
• Available webhook types
  • ApplicationReceivedV2
  • JobCreated
  • PostAdded
  • PostDeleted
  • PostFailed
  • PostUpdated
• Webhook requests

This webservice allows to create, list, and delete webhook subscriptions for various types of events that occur in the idibu system.

A webhook is an HTTP request that the idibu system will send to a URL defined by you whenever some event(s) chosen by you for the given webhook occur.

For any account, any number of subscriptions, for any combination of events can be created, and different URLs specified for the callbacks, with an option to sign the payload for authorization.

Each event type comes with its own set of HTTP parameters present in the body of the request - the parameters define various objects related to the event that can be further queried and managed using other webservices.

All requests are queued and, depending on current traffic, may not arrive immediately.

Creating or updating a webhook subscription

This method allows to subscribe to any type of webhook available in the system.

The url specified as part of the subscription is the one that the system will send HTTP requests to whenever the specified event types occur. It also uniquely identifies the webhook - performing the call with the same url will update an existing subscription.

The optional secret parameter (used to authenticate the requests) will not be returned as part of the Listing webhook subscriptions method and therefore needs to be managed externally.

Endpoint

https://ws.idibu.com/ws/rest/v1/webhooks

Available methods

POST /

Sets up a subscription for events specified in the data.

Query parameters

Parameter Name	Type restrictions	Required?	Notes
hash	String	Yes	Hash of the idibu account to which the request pertains.
data	String	Yes	The full query XML (see the Query format below), URL-encoded within the parameter.

Query format

<subscription>
  <url>[string:url]</url> <!-- URL to which the data will be sent whenever the event(s) occur(s); uniquely identifies the webhook -->
  <types>[string]</types> <!-- comma-separated list of event types; see "Available webhook types" below -->
  <secret>[string]</secret> <!-- optional; will be used to sign the webhook HTTP request body using HMAC-SHA256 algorithm with the bytes of the provided 'secret' as a key. The resulting hash is put in the 'authorization' header of the webhook HTTP request. -->
</subscription>

Response format

<idibu generator="idibu" version="1.0">
  <response>[string]</response> <!-- 'Subscription created.' for a new <url> or 'Subscription updated.' for an existing <url>; or an error <message> -->
  <status>["success"|"failed"]</status> <!-- whether the request succeeded or not -->
</idibu>

---

Listing webhook subscriptions

This method allows to list all the webhooks the account is currently subscribed to.

The secret parameter (used to authenticate the requests), which can be optionally defined while Creating or updating a webhook subscription will not be returned as part of this call.

Endpoint

https://ws.idibu.com/ws/rest/v1/webhooks

Available methods

GET /

Lists all webhooks to which the account is currently subscribed.

Query parameters

Parameter Name	Type restrictions	Required?	Notes
hash	String	Yes	Hash of the idibu account to which the request pertains.

Response format

<idibu generator="idibu" version="1.0">
  <response>
    <subscriptions>
      <subscription> <!-- can be multiple -->
        <url>[string:url]</url> <!-- URL to which the data will be sent whenever the event(s) occur(s); uniquely identifies the webhook -->
        <types>[string]</types> <!-- comma-separated list of event types; see "Available webhook types" below -->
        <modified>[string:date]</modified> <!-- last modification date; YYYY-MM-DD HH:mm:ss -->
      </subscription>
    </subscriptions>
  </response>
  <status>["success"|"failed"]</status> <!-- whether the request succeeded or not -->
</idibu>

---

Deleting a webhook subscription

This method allows to remove an existing webhook subscription.

Endpoint

https://ws.idibu.com/ws/rest/v1/webhooks

Available methods

DELETE /[url]

Removes the webhook with the provided [url]. Please make sure to URL-encode the [url].

Query parameters

Parameter Name	Type restrictions	Required?	Notes
hash	String	Yes	Hash of the idibu account to which the request pertains.

Response format

<idibu generator="idibu" version="1.0">
  <response>[string]</response> <!-- 'Subscription deleted.' or an error <message> -->
  <status>["success"|"failed"]</status> <!-- whether the request succeeded or not -->
</idibu>

---

Available webhook types

Below is the list of all currently available event types, with their description and details of the HTTP request they would generate.

ApplicationReceivedV2

Triggered whenever a new candidate arrives on the account.

The following parameters will be passed in the body of the request:

Parameter Name	Type restrictions	Notes
event_id	GUID	ID of the event in idibu's database; please provide it when contacting support.
type	String	ApplicationReceived
client_id	Integer	ID of the idibu account.
sender_id	Integer	ID of the account's User for whose advert the candidate applied. Refer to the User Management Webservice.
job_id	Integer	ID of the Job for which the candidate applied. Refer to the Job Management Webservice.
job_reference	String	Reference of the Job for which the candidate applied. Refer to the Job Management Webservice.
job_title	String	Title of the Job for which the candidate applied. Refer to the Job Management Webservice.
postlog_id	Integer	ID of the Post for which the candidate applied. Refer to the Advert Management Webservice.
aptrack_id	Integer	ID of the candidate. Refer to the Applicant Management Webservice.
from	String (email)	Candidate's email address.
portal_id	Integer	ID of the Portal from which the candidate arrived. Refer to the Portal Management Webservice.
date	Date and time Format: YYYY-MM-DD HH:mm:ss	The moment of the candidate reaching idibu system.

JobCreated

Triggered whenever a new Job is created on the account. Please note that a 'job' object is not the same as a 'vacancy' used in the idibu V3 system. See here for more details.

The following parameters will be passed in the body of the request:

Parameter Name	Type restrictions	Notes
event_id	GUID	ID of the event in idibu's database; please provide it when contacting support.
type	String	JobCreated
client_id	Integer	ID of the idibu account.
sender_id	Integer	ID of the account's User that created the Job. Refer to the User Management Webservice.
job_id	Integer	ID of the Job. Refer to the Job Management Webservice.
job_reference	String	Reference of the Job. Refer to the Job Management Webservice.
job_title	String	Title of the Job. Refer to the Job Management Webservice.
date	Date and time Format: YYYY-MM-DD HH:mm:ss	The moment of the Job's creation.

PostAdded

Triggered whenever a successful posting leaves the posting queue.

Please keep in mind that whether the Post is a successful posting, successful update, or unsuccessful posting is not pre-defined and depends on the response that idibu receives from the given Portal (posting destination) after the posting attempt.

The following parameters will be passed in the body of the request:

Parameter Name	Type restrictions	Notes
event_id	GUID	ID of the event in idibu's database; please provide it when contacting support.
type	String	PostAdded
client_id	Integer	ID of the idibu account.
sender_id	Integer	ID of the account's User that posted the ad. Refer to the User Management Webservice.
job_id	Integer	ID of the Job. Refer to the Job Management Webservice.
job_reference	String	Reference of the Job. Refer to the Job Management Webservice.
job_title	String	Title of the Job. Refer to the Job Management Webservice.
advert_id	Integer	ID of the Advert. Refer to the Advert Management Webservice.
postlog_id	Integer	ID of the Post. Refer to the Advert Management Webservice.
portal_id	Integer	ID of the Portal to which the Post was sent. Refer to the Portal Management Webservice.
date	Date and time Format: YYYY-MM-DD HH:mm:ss	The moment of the Post reaching the Portal.

PostDeleted

Triggered whenever a successful deletion leaves the posting queue.

Please keep in mind that whether the Post is a succcessful deletion or unsuccessful deletion is not pre-defined and depends on the response that idibu receives from the given Portal (posting destination) after the deletion attempt.

The following parameters will be passed in the body of the request:

Parameter Name	Type restrictions	Notes
event_id	GUID	ID of the event in idibu's database; please provide it when contacting support.
type	String	PostDeleted
client_id	Integer	ID of the idibu account.
sender_id	Integer	ID of the account's User that posted the ad. Refer to the User Management Webservice.
job_id	Integer	ID of the Job. Refer to the Job Management Webservice.
job_reference	String	Reference of the Job. Refer to the Job Management Webservice.
job_title	String	Title of the Job. Refer to the Job Management Webservice.
advert_id	Integer	ID of the Advert. Refer to the Advert Management Webservice.
postlog_id	Integer	ID of the Post. Refer to the Advert Management Webservice.
portal_id	Integer	ID of the Portal to which the Post was sent. Refer to the Portal Management Webservice.
date	Date and time Format: YYYY-MM-DD HH:mm:ss	The moment of the Post reaching the Portal.

PostFailed

Triggered whenever an unsuccessful posting or deletion leaves the posting queue.

Please keep in mind that whether the Post is a succcessful posting, successful update, successful deletion, or unsuccessful posting or deletion is not pre-defined and depends on the response that idibu receives from the given Portal (posting destination) after the posting or deletion attempt.

The following parameters will be passed in the body of the request:

Parameter Name	Type restrictions	Notes
event_id	GUID	ID of the event in idibu's database; please provide it when contacting support.
type	String	PostFailed
client_id	Integer	ID of the idibu account.
sender_id	Integer	ID of the account's User that posted the ad. Refer to the User Management Webservice.
job_id	Integer	ID of the Job. Refer to the Job Management Webservice.
job_reference	String	Reference of the Job. Refer to the Job Management Webservice.
job_title	String	Title of the Job. Refer to the Job Management Webservice.
advert_id	Integer	ID of the Advert. Refer to the Advert Management Webservice.
postlog_id	Integer	ID of the Post. Refer to the Advert Management Webservice.
portal_id	Integer	ID of the Portal to which the Post was sent. Refer to the Portal Management Webservice.
date	Date and time Format: YYYY-MM-DD HH:mm:ss	The moment of the Post reaching the Portal.

PostUpdated

Triggered whenever a successful update leaves the posting queue.

Please keep in mind that whether the Post is a succcessful posting, successful update, or unsuccessful posting is not pre-defined and depends on the response that idibu receives from the given Portal (posting destination) after the posting attempt.

The following parameters will be passed in the body of the request:

Parameter Name	Type restrictions	Notes
event_id	GUID	ID of the event in idibu's database; please provide it when contacting support.
type	String	PostUpdated
client_id	Integer	ID of the idibu account.
sender_id	Integer	ID of the account's User that posted the ad. Refer to the User Management Webservice.
job_id	Integer	ID of the Job. Refer to the Job Management Webservice.
job_reference	String	Reference of the Job. Refer to the Job Management Webservice.
job_title	String	Title of the Job. Refer to the Job Management Webservice.
advert_id	Integer	ID of the Advert. Refer to the Advert Management Webservice.
postlog_id	Integer	ID of the Post. Refer to the Advert Management Webservice.
portal_id	Integer	ID of the Portal to which the Post was sent. Refer to the Portal Management Webservice.
date	Date and time Format: YYYY-MM-DD HH:mm:ss	The moment of the Post reaching the Portal.

---

Webhook requests

Every webhook, when triggered, will send an HTTP POST request to the URL endpoint defined for that specific subscription.

The request's content-type header is always application/x-www-form-urlencoded, with all parameters (as defined in the section above) passed as form values.

Additionally, the authorization header is provided if the optional secret parameter has been defined for the webhook subscription (please check the Query format for more details).