Configuring webhooks

Follow
Available for Roles Super Admin
Permissions • Manage API credentials and manage integrations
Packages LeverTRM, LeverTRM for Enterprise

Webhooks allow you to define certain types of events that occur in your Lever instance as "triggers" that can initiate an action in an integrated platform. Webhooks are typically configured when setting up an integration between Lever and another platform in your tech stack.


How webhooks work

A webhook is a mechanism in a software platform that allows real-time communication between different applications or services. It enables one application to send automatic notifications or data updates to another application by sending an HTTP request to a predefined URL (the webhook endpoint). The receiving application can then process the incoming data and trigger appropriate actions based on the received information. Webhooks are commonly used for event-driven integrations, such as notifying external systems about specific events or synchronizing data between different applications.

Most of the events for which you can generate webhooks pertain to the opportunity associated with a candidate. Some events connect to actions taken with an interview associated with an opportunity. One example would be to use the ‘Candidate Stage Change’ event to automatically trigger a request in your background check platform when a candidate’s opportunity reaches the 'Background Check' stage in Lever. Another common example is using the ‘Candidate Hired’ event to automatically generate an employee record in your HRIS for a candidate when their opportunity is marked as 'Hired' in Lever.

In Lever, you can configure webhooks for the following events:

  • Application created - Triggers when a candidate application is created
  • Candidate stage change - Triggers when a candidate's opportunity changes stages
  • Candidate archive state change - Triggers when a candidate's opportunity is archived or unarchived
  • Candidate hired - Triggers when a candidate's opportunity is marked as 'Hired'
  • Candidate deleted - Triggers when a candidate's opportunity is deleted
  • Interview created - Triggers when an interview is created
  • Interview updated - Triggers when an interview is updated
  • Interview deleted - Triggers when an interview is deleted

To learn more about how Lever implements webhooks, refer to the 'Webhooks' section of our developer documentation.

Configuring webhooks

To configure webhooks in Lever:

  • Navigate to Settings > Integrations and API > Webhooks
  • Locate the event for which you wish to configure a webhook and click the caret (ˇ) aligned to the right of the URL field (when empty, this field reads "https://yoursite.com")

Webhook settings page

  • If you wish to exclude candidate opportunities of a specific origin, de-select the corresponding checkboxes below the URL field
    • For example, if you were configuring a 'Candidate Hired' webhook, you make wish to exclude internal candidates (those with an opportunity origin of 'Internal') from having a new employee record created in your HRIS when their opportunity is marked as 'Hired' since one likely already exists for them.

Candidate stage change webhook fields expanded; URL field is empty event toggle is inactive

  • Copy the signature token and paste it into the appropriate field in the integrating platform
    • When setting up an integration between Lever and another platform, the platform you are integrating with will typically prompt you to provide a signature token as part of its integration setup process.
    • Some integrations may also require you to input an API key in addition to the signature token. Refer to our API key help article to learn how to generate an API key in Lever. Since every integration's setup process can be different, we highly advise reading the help article for the specific integration you are attempting to enable.
    • Once you have input the signature token, the integrating platform should provide you with a webhook URL, which you will need for the next step of the process.
  • Paste the webhook URL from the integrating platform into the URL field

Candidate stage change webhook fields expanded; URL field is populated with webhook URL and event toggle is inactive

  • Test the webhook connection by clicking the Verify Connection button
    • At the bottom of the webhook settings page, you will find a list of all webhook deliveries made in the last two weeks, including test "triggers" initiated by clicking the Verify Connection button.
  • Once you have confirmed that the webhook is properly connected, click the toggle next to the event name to activate the webhook
    • The webhook will turn blue to indicate that it is active.

Candidate stage change webhook fields expanded; URL field is populated with webhook URL and event toggle is active

You can associate multiple webhooks with a single event. Simply click + Add webhook under the event toggle and repeat the steps above to configure additional webhooks. For example, here's what it would look like if you had webhooks configured for two separate integrations that relied on the 'Candidate Stage Change' event.

Candidate stage change webhook enabled for more than one integration.

Note that activating an event toggle enables all webhooks associated with that toggle.

Troubleshooting webhook issues

If you are experiencing issues with an integration that relies on webhooks, check the webhooks delivery log to diagnose the problem. The webhooks delivery log can be found under the 'Recent webhook delivery' heading at the bottom of the webhook settings page. Here you will find a list of the last 1000 webhook deliveries made within the previous two weeks.

Click the caret (ˇ) aligned to the right of a delivery entry to reveal the date and time of the delivery as well as the POST payload and the response from the integrated platform. To re-attempt delivery, click the Rerun button.

Live image of webhook delivery entry changing between Request and Response tab

Deleting and reconfiguring webhooks

To delete a webhook, click the caret (ˇ) aligned to the right of the webhook URL and click Delete.

Candidate stage change webhook fields expanded; Delete buttons is highlighted

Note that deleting a webhook is not the same as de-activating a webhook event toggle. The latter will disable the webhooks associated with the event but keep the signature token and URL intact.

Regenerating signature tokens

If at any point you regenerate a signature token for an existing webhook, note that the token will need to be updated in all integrated platforms in which it is used in order for the integration to function correctly. This also applies for webhooks that are deleted and later re-created, as the re-created webhook's signature token will be different.

Was this article helpful?
0 out of 0 found this helpful