A web hook is a simple event notification system. When an event occurs in Greenhouse Recruiting (e.g. 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. Web hooks 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 web hooks on our Developer Resources page.
Enable a Web Hook
To create a web hook, 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 web hook:
- Name this web hook: We recommend choosing a name that specifies for what the web hook is being used.
- When: Select the web hook you want to enable (i.e. 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 web hook fails. There is no in-app notification if the web hook 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 web hook headers as required, and configure the number of retry attempts Greenhouse Recruiting will make if the web hook 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 web hook 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 web hook.
If the web hook 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 web hook again. Repeat until configurations are saved and the web hook is enabled.
Troubleshoot a Web Hook Error
In some cases, a web hook might fire without issue but still send a web hook 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 web hook failed.