A webhook is a simple event notification system. When an event occurs in Greenhouse Recruiting (for example, a candidate is hired) a payload of data about the event is sent to a specified endpoint. Typically this endpoint is developed and hosted on an integration platform or external system managed by your internal team or a third-party. Webhooks can be enabled for integrations with our partners and custom integrations developed by your team. Your development team can find more information about our available webhooks on our Developer Resources page.
Enable a webhook
To create a webhook, click the Configure icon in the upper right-hand corner of the page. Navigate to Dev Center on the left-hand panel, then click Web Hooks from the Dev Center page.
Click Web Hooks from the subsequent page.
Fill in the following fields for the webhook:
- Name this web hook: We recommend choosing a name that specifies for what the webhook is being used.
- When: Select the webhook you want to enable (that is, the event that will trigger the payload to be sent).
- Endpoint URL: The URL that will receive the data (must be HTTPS).
- Secret Key: This can be any value.
- Error recipient email: This is the email address that will receive an email notification if the webhook fails. There is no in-app notification if the webhook fails, so we recommend specifying an internal Greenhouse Recruiting admin who should receive the notification.
- Advanced Settings: Add data to the Advanced Settings if your receiving endpoint requires additional Basic or OAuth authentication. Here you can also add additional webhook headers as required, and configure the number of retry attempts Greenhouse Recruiting will make if the webhook fails. The default number of retry attempts is 25. You can find more information about our retry policy in our developer documentation here.
Click Create Web hook to complete the webhook setup. Greenhouse Recruiting will ping your endpoint. If this ping is accepted successfully, the endpoint will be created.
If the ping is unsuccessful, Greenhouse Recruiting will save the configurations but disable the webhook.
If the webhook is disabled due to the endpoint ping failing, edit the web hook's configurations to resolve the source of the error, then set the Disabled? option to No. Click Update Web hook to try saving the webhook again. Repeat until configurations are saved and the webhook is enabled.
Troubleshoot a webhook error
In some cases, a webhook might fire without issue but still send a webhook error message to the error recipient email address.
If the error email states a 500 Internal Server Error occurred, this indicates the provided endpoint URL was unable to receive the payload successfully. To troubleshoot this, we recommend contacting the developer or other individual who provided you with the endpoint URL to determine more about why the webhook failed.