A web hook is a simple event notification system. When an event occurs in Greenhouse Recruiting – for example, when a candidate is hired – and a web hook is configured, data about the event is sent to a specified destination called an endpoint.
Typically this endpoint is developed and hosted on an integration platform or external system managed by your team or a third-party vendor. Web hooks can be enabled for integrations with our partners and custom integrations developed by your team.
You can find more information about web hooks in our Developer Resources.
Enable a web hook
To enable a web hook, click the Configure icon on your navigation bar, and select Dev Center on the left.
Click Web Hooks on the Dev Center page.
Click Web Hooks from the next page.
On the Create a Web Hook page, enter the following fields for the web hook:
- Name this web hook: A name that specifies what the web hook is being used for.
- When: The event in Greenhouse Recruiting that will cause the web hook to activate.
- Endpoint URL: The URL that will receive the data (must be HTTPS).
- Secret Key: A secret phrase or key used that the receiving endpoint / application may use 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 application.
- Error recipient email: 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 choosing an internal Greenhouse Recruiting admin who should receive the notification.
If needed, you can configure Advanced Settings if your receiving endpoint requires additional Basic or OAuth authentication. You can also add additional web hook headers and configure the number of retry attempts Greenhouse Recruiting will make if the web hook fails.
Click Create Web hook to complete the web hook setup.
When you create a new web hook, Greenhouse Recruiting sends a ping to your endpoint to verify that the connection is working. If this ping is accepted successfully, the endpoint will be created.
If the ping is unsuccessful, Greenhouse Recruiting will save the configurations but deactivate the web hook.
If the web hook is deactivated because the endpoint ping failed, edit the web hook's configuration and fix the error. To re-enable the web hook to try again, change the Disabled? section to No and click Update Web hook.
Troubleshoot a web hook error
In some cases, a web hook might activate without issue but still send a web hook error message to the error recipient's email address.
If the error email states a
500 Internal Server Error occurred, the provided endpoint URL was unable to receive the payload successfully.
To troubleshoot this error, we recommend contacting the developer or other individual who provided you with the endpoint URL for more information on the error.