Skip to main content
SmartRecruiters

Use of Webhook Subscription API

 

How it works:

 

Webhook Subscription API is a part of the Customer API, and allows the user to subscribe to a certain event or a group of events: to register a certain URL, which SR will send notifications to. URL registration process is similar to the registration of notification url inside the Marketplace API, but takes place within Webhook Subscription API.

 

This API  introduces a “client-server” role in reverse. Until now, the user needed to call SR API endpoint in order to obtain data- this gets rid of the need for periodic checks and allows the user to set the integration to call endpoints only when there are changes. This API is limited to certain events. 

The full list of events is represented by the POST endpoints, and can be found in the CALLBACKS overlap: https://dev.smartrecruiters.com/customer-api/live-docs/webhooks-subscriptions-api/#/

 

Getting started

Authentication

 

The authentication mechanism makes sure that the server is “live” to avoid DDOS attacks and spammers. The URL needs to be tested first in order for our system to recognize it and send the notifications. One account is not equal to one URL- the user can activate multiple callbackURLs.

To activate the URL:

1. call  POST/subscriptions

https://dev.smartrecruiters.com/customer-api/live-docs/webhooks-subscriptions-api/#/subscriptions/subscriptions.create

Required: 

-callback URL

-names of events you want (cannot put multiple, must be done separately for each event)

 

The response body will return “id” [subscription identifier]

Example of a response body after a correct call: 

 

{

  "id": "u83it9o93y75j645",

  "callbackUrl": "https://server.com/send/callback/here",

  "events": [

    {

      "name": "job.created",

      "version": "1.0.0"

    }

  ],

  "status": "inactive"

}

 

2.call  PUT/subscriptions/{id}/activation

https://dev.smartrecruiters.com/customer-api/live-docs/webhooks-subscriptions-api/#/subscriptions/subscriptions.activate

 

Required:

-“id” [subscription identifier]- returned in the previous endpoint
 

The authentication process needs to be conducted in the context of a single callback URL. 

An individual user can register up to 20 subscriptions.


Notifications:

In the request body of POST/subscriptions you can specify the email address that will receive the notification as well.

 

{

  "callbackUrl": "https://server.com/send/callback/here",

  "events": [

    "job.created"

  ],

  "alertingEmailAddress": "webhook.alerts@domain.com"

}

 

URL: https://api.smartrecruiters.com/webhooks-api/v201907/subscriptions

 

Example of a working request body:

 

{

"callbackUrl": "https://www.server.com/send/callback/here",

"events": [

"candidate.created"

],

"alertingEmailAddress": "konradtestujesr@gmail.com"

}

 

Response:

 

{

  "id": "c28725f0-345b-47fc-87c6-65ffeded80e1",

  "callbackUrl": "https://www.server.com/send/callback/here",

  "events": [

    {

      "name": "candidate.created",

      "version": "v1"

    }

  ],

  "status": "inactive",

  "alertingEmailAddress": "konradtestujesr@gmail.com"

}

 

In the response body you will receive “id”- use it to activate the subscription.
 

Workflow:

  1. 1. Subscribe to a Webhook

  2.  

    Correctly created webhook will return the “id”. Use it below to activate the subscription.

  3. Activate a webhook

  4. Repeat for all the events you’d like to get notifications about

  5. The user can use an email address to add notification- this could be used as a workaround for 3rd party applications that push candidates to Smartrecruiters. Such events do not trigger notification email to the hiring team- only candidates who applied via job boards trigger built-in notification emails.

    Deleting subscription

    Receiving too many notifications? You can delete the subscription any moment by providing the subscription id in the following endpoint: DELETE/subscriptions/{id}

    Testing

    To test the app use Heroku: https://sr-webhooks-client.herokuapp.com/

  6. Log in to your Smartrecruiters account) Create App

    1. Activate app

    2. Go to Smartrecruiters account and perform the action you subscribed to (in this case, create a candidate)

    3. Receive the notification

    Limitations: no email notifications. The testing app only simulates the email notification. It does not actually send out any emails.

    Proper requests use

    The webhooks are general, not specific- user cannot register the webhook to send notifications only for certain candidates or jobs. There are no ids that can be registered to send notification only when eg. candidate reaches a certain step in Hiring Process. 

    Example: application.status.updated webhook will send notification about ALL the candidates that change the status inside any job.

    Moving the candidate from New to Hired through sub statuses is being represented as below:

    The Webhook returns information about a candidate changing their status inside specific job, but does not specify the status they’ve reached. User cannot choose to see information only about certain candidate, all candidates and all jobs are returned.

    The fact that this candidate has been hired was not reflected in the Webhook notification. However, this process can be automated and these notifications can be used as triggers. The user can automate this action by associating such Webhook notification with an automatic call to GET/postings/{uuid}/candidates/{candidateId}/status

     

    Example: using the below request body to monitor only one candidate inside one job will not work

     

    {

    "events": [

    "application.status.updated",

    {

    "job_id": "332842da-5d2b-4769-b775-1424cb68549c",

    "candidate_id": "b89b4b86-0f75-460e-b508-9600de4d19b3"

    }

    ]

    }


     

    The correct request in this case is:

     

    {

      "events": [

        "application.status.updated"

      ]

    }

     

    This means that there is no need to replicate registration of webhooks for each candidate separately- one request with specific event will monitor all the candidates.

     

    ID glossary

     

    CallbackURL- URL that the notifications about the events will be sent to, user-generated

    Subscription “id”- individual id of each registered subscription, returned in the response body of POST/subscriptions/ the only way to obtain it is to call this endpoint 

    Event-version- returned in POST/subscriptions body, once called/ the only way to obtain it is to call this endpoint

    X-Hook-Secret- might be misleading, we do not affect this header in any way, it is sent automatically by SR to the server, that the user is trying to register. It is randomly generated.

    FAQ

     

    Q: I cannot activate the new webhooks. I receive a 424 Error. Any idea why?

    curl -X PUT "https://api.smartrecruiters.com/webh...355/activation" -H "accept: */*" -H "X-SmartToken: 31b1db51be4c4fa78f4089a3365ab0ad"

    {

    "errors": [

    {

    "code": "HANDSHAKE_FAILED",

    "message": "Server did not responded to handshake within 20000 ms"

    }

    ]

    }
     

    A: it means that your server did not respond within 20 seconds.

     

    PUT/subscriptions/{id}/activation

    To ensure that target server is ready to consume notifications, we require you to implement the initial handshake.

     

    Having subscription with callbackUrl: https://example.org/hook, during activation we will make POST request with X-Hook-Secret header:

     

    POST https://example.com/hook

    X-Hook-Secret: 4jn8fs9011jj8

    We expect your server to respond within the time of 20 seconds with HTTP 200 response containing X-Hook-Secret header with same value.

     

    Response 200

    X-Hook-Secret: 4jn8fs9011jj8

     

    Q: “No permission to manage webhooks” 

    A: The account you’re trying to reach needs to have Webhooks enabled. Please contact your Partner Operations consultant to make sure this feature is enabled.

     

    Q: I get a code 200 and an empty response:

    Webhook details:

    GET https://api.smartrecruiters.com/webh.../subscriptions

     

    Response:

    [

        {

            "id": "562d07ad-b6bb-4e7d-a751-d114e540c2df",

            "callbackUrl": "https://integrations.harver.com/prod...b5c43f9b9792dd",

            "events": [

                {

                    "name": "application.status.updated",

                    "version": "v1"

                }

            ],

            "status": "active"

        }

    ]


     

    Retrieve callback requests:

    GET https://api.smartrecruiters.com/webh.../callbacks-log

    Response: status code 200 + []

    Why?
     

    A: Check if the subscription you’re pulling is registered for a correct account. The API key, accountID and subscription ID must be aligned and assigned to the same account.

     

    Q: What are the differences between registering webhooks using customer’s API key and OAuth refresh token?

     

    A: Using OAuth, they won’t be visible to other users. Example:

    Marc adds subscription

    Edgar adds subscription

    Edgar sees subscription added by Marc

    Marc sees subscription added by Edgar

    Marc sees his and Edgars subscriptions

    OAuth app using Marcs credentials can not see subscription which he added

    OAuth app adds subscription on Marc behalf

    Marc can not see subscription which OAuth app added on his behalf

    OAuth app adds subscription on Edgar behalf

    OAuth app using Edgars credentials can not see subscription added on Marc behalf

    OAuth app using Marcs credentials sees only subscription added on his behalf

    Marc activates subscription added by Edgar

    Marc can not activate subscription added by OAuth app on his behalf

    OAuth app using Marcs credentials can not activate subscription added by him

    OAuth app using Marcs credentials activates subscription which it added on his behalf

    Marc can delete subscription added by Edgar

    Marc can not delete subscription added by OAuth app on his behalf

    OAuth app using Marcs credentials can not delete subscription added by himself

    OAuth app using Marc credentials can not delete subscription added od Edgar behalf

     

    To sum up: Generally, if a user creates webhooks using their API key, i.e. as himself, his webhooks are seen by other admins, but when it is done through oauth apps, the user sees only his webhooks using the oauth app.

     

    Q: Which Smartrecruiters team is responsible for troubleshooting Webhooks and Heroku app?

    A: Public API team

     

    Q: Nothing happens when i click “Create” inside the demo app

    A: this means that the request body is incorrect, Heroku app does not return any errors, it will simply close the request window