Webhooks

Overview

Webhooks available for our Customer API allow developers to subscribe to entity changes in the system instead of polling for updates. A webhook notifies your application by sending outgoing HTTP requests to a URL of your choosing.

The Webhooks Subscription API exposes endpoints you can use to create webhooks, define the events notifications you want to receive, set callback URLs, and remove webhooks when they are no longer needed. 

If your application is integrating using OAuth 2.0, you will need to ensure you have included the necessary access scopes to create a webhook. 

 Learn more about the different options for connecting to our Customer API. 

Creating webhook subscriptions

Every aspect of webhooks creation and management is controlled through the Webhooks subscription API at this time. A subscription object is composed of a callback URL and the array of events that the consumer would like to be notified about. 

To create a webhook, use the following endpoint: 

POST /subscriptions

Specify the callback URL and the list of events your application is interested in. You can include as many events as you would like.

You can find the full list of available event subscriptions under the “Callbacks” tab of the POST /subscriptions endpoint in Live Docs.

Activating webhook subscriptions 

Before we can deliver any webhook notifications, we need to ensure that your server is prepared to accept these notifications. Use the following endpoint to activate each new subscription: 

PUT /subscriptions/{id}/activation

SmartRecruiters will make a POST request containing a header named “X-Hook-Secret” and unique value to the callback URL you defined when creating the subscription. 

Within 20 seconds, we expect your server to respond with an HTTP 200 response containing the “X-Hook-Secret” header and the same value. You will then receive a 204 response from us that signals the subscription was successfully activated. 

As soon as you have activated your subscription, we will start delivering notifications based on those event triggers. You will receive all notifications for events you subscribe to and will have to determine which you would like to act on.

Receiving webhook notifications 

Every webhook notification you receive contains information about type of event and its version in the headers. The id of the changed resource is provided in the body. Example body:

{   
"id": "string"
}

You will also find a header called link in the notification request. Use this link to retrieve the current state of the resource via one of our Customer API endpoints. 

We consider a notification to be successfully delivered when we receive a 202 response from your server for each notification. 

Any other response code or client timeout will be considered as a failed delivery. We will attempt to re-deliver a webhook notification up to 3 times after the initial failure. The retry cadence is as follows: 

  • 15 seconds after first delivery failure
  •  2 minutes after second delivery failure
  • 15 minutes after third delivery failure

Managing webhook subscriptions

Retrieve a list of your webhook subscriptions or a specific subscription: 

GET /subscriptions

GET /subscriptions/{id}

If your application is integrating via OAuth, you will only be able to see the list of webhook subscriptions created by your application for the specific authorizing user. You will not have access to webhook subscriptions created on behalf of other users or by other applications. 

Deleting a webhook subscription also deactivates it: 

DELETE /subscriptions/{id}

You can always subscribe to more events using the same callback URL by creating new subscriptions. Currently, you will not be able to remove events from webhook subscriptions. You must delete the subscription and create a new subscription with the updated array of events you would like to subscribe to and activate it again. 

Webhooks Demo App 

We’ve built a demo OAuth application that you can play around with to get a sense of how our new webhooks notifications function. You will need a SmartRecruiters user account with Administrator system role to test the demo app. 

Find the app here: https://sr-webhooks-client.herokuapp.com/

The demo application facilitates an OAuth authentication with a SmartRecruiters user account, provides an endpoint for receiving webhooks notifications and also supports the initial activation handshake. 

Users will be able to see the notification data, see the current state of entities and also change their webhook subscriptions.

The link header of the notification request provides the URL that can be used to retrieve the current state of the resource. The demo application uses the link just after receiving the webhook notification, obtains the data and presents the actual state of entity.