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 10 times from the initial failure. The retry cadence will follow an exponential back-off strategy as following: 

  • 1 minute after first delivery failure
  • 3 minutes after second delivery failure
  • 10 minutes after third delivery failure
  • 45 minutes after fourth delivery failure
  • 120 minutes (2 hours) after fifth delivery failure 
  • … up to 1440 minutes (24 hours) after ninth delivery failure

Additionally, we will also send a notification email to the email address you have set in alertEmailAddress field when your service was creating the webhook subscription when the webhook notification fails to deliver. In the events which your server failed to receive the webhook notification after the retries, you have the option to retrieve the webhook events log from the past 30 days, for both failed and success webhook events with:

GET /subscriptions/{id}/callbacks-log

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.

Troubleshooting

There are times you may receive errors when accessing our Webhook subscription endpoints or not able to receive our callback notification. This section provide some common ways to narrow down cause of error and resolve some of them.

Using Custom Authentication

We provide the ability for you to define your custom authentication in the webhook header when you are creating a new webhook subscription. If you use a custom authentication header, when we send the notification to your service, the custom authentication header will be included in the header of the callback.

We support 3 different types of custom authentication:

  1. Basic authentication header using username and password
  2. Custom authentication header using self-defined header and value
  3. OAuth 2.0 Client Credential using access token exchanged from a specified clientId and clientSecret

To illustrate the use of a custom authentication header, below are two example calls for notification we make to your service with and without custom authentication.

Without custom authentication header:

curl -v -H "Accept: application/json" -H "Content-Type: application/json" --data '{"id":"example"}' https://your-host.com/path/to/webhook 

With custom authentication header

curl -v -H "CUSTOM_SECURITY_HEADER_NAME: CUSTOM_SECURITY_KEY" -H "Accept: application/json" -H "Content-Type: application/json" --data '{"id":"example"}' https://your-host.com/path/to/webhook

Where CUSTOM_SECRUITY_HEADER_NAME will be the value you defined in callbackAuthentication.headerName and CUSTOM_SECURITY_KEY will be the value you defined in callbackAuthentication.headerValue when creating a new webhook subscription. In either cases, we expect your service to response with HTTP 202 to acknowledge you’ve received the notification

We expect a valid certificate is used for HTTPS connect and we do not accept self-signed certificates.

Publicly Accessible

When using SmartRecruiters webhook, please ensure your service is publicly accessible so that our callback notification can reach your service. There are two quick tests you can perform to check if your service is publicly accessible:

Your service/webhook can reply with HTTP 202 for the following call:

curl -v -H "Accept: application/json" -H "Content-Type: application/json" --data '{"id":"example"}' https://your-host.com/path/to/webhook

Your service/webhook can reply with HTTP 200 and that the response contains “X-Hook-Secret: test” header for the following call:

curl -v -H "Accept: application/json" -H "Content-Type: application/json" -H "X-Hook-Secret: test" --data '{}' https://your-host.com/path/to/webhook