Configuring webhooks

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")

• 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.

• 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

• 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.

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.

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.

Deleting and reconfiguring webhooks

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

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.