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"}'

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"}'

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"}'

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 '{}'


Q: How to check what webhook notifications were sent and what is their status?

A: You can do it using GET/subscriptions/{id}/callbacks-log endpoint. You need to specify your subscription identifier for which you want to search for sent notifications. You can also provide additional arguments like callbackStatus to find only successful or failed callbacks or before/after to search only in given time period. In the response you will find the details of the callback requests. You can find there an information about request (url, headers, body) as well as status and timestamp.

Did this page help you?