A webhook is a simple event notification system. When an event occurs in Greenhouse Recruiting – for example, when a candidate is hired – and a webhook is configured, data about the event is sent to a specified destination called an endpoint.
Typically a webhook's endpoint is developed and hosted on a partner integration platform or an external system managed by your team or a third-party vendor.
While you can't preview a webhook's payload, you can see example data for each webhook event in our Developer Resources.
Create a webhook
To create a new webhook, click the Configure icon on your navigation bar and select Dev Center on the left.
Click Web hooks.
Click Web hooks on the next page.
Enter the following fields to configure your new webhook:
- Name this webhook: A name that specifies what the webhook is being used for.
- When: The event in Greenhouse Recruiting that causes the webhook to activate.
- Endpoint URL: The URL that will receive the data (must be https).
- Secret Key: A secret phrase or key used by the receiving endpoint / application to verify that the data is legitimate. You can enter any value for your secret key, but it must match up with the secret key in the receiving app.
- Error recipient email: The email address that will receive an email notification if the webhook fails. Because there isn't an in-app notification if a webhook fails, we recommend choosing a Greenhouse Recruiting admin to receive the email notification.
If needed, you can configure Advanced Settings should your receiving endpoint require additional Basic or OAuth authentication. You can also configure additional webhook headers and manage the number of retry attempts Greenhouse Recruiting will make if the webhook fails.
Note: The default number of retry attempts is five (5). You can find more information about our retry policy in our developer documentation.
Click Create webhook to complete the webhook setup.
When you create a new webhook, Greenhouse Recruiting will send a ping to your endpoint to verify the connection's working. If the ping is accepted successfully, the webhook will be created. If the ping is unsuccessful, Greenhouse Recruiting will save the configuration but deactivate the webhook.
Note: If the webhook is deactivated automatically because the endpoint ping failed, scroll to Edit Web Hook and edit the webhook's configuration to fix the error. To re-enable the webhook to try again, change the Disabled? section to No and click Update webhook.