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 this endpoint is developed and hosted on an integration platform or external system managed by your team or a third-party vendor. 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
Click the Configure icon in the upper right corner of the page and navigate to Dev Center on the left panel.
Click Web Hooks on the Dev Center page.
Click Web Hooks from the next page.
Fill in the following fields for the webhook:
- Name this web hook: A name that specifies for what the webhook is being used.
- When: The event in Greenhouse Recruiting that will cause the webhook 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 application uses 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 webhook fails. There is no in-app notification if the webhook 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 webhook headers and configure the number of retry attempts Greenhouse Recruiting will make if the webhook fails.
Click Create Web hook to complete the webhook setup.
When you create a new webhook, 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 disable the webhook.
If the webhook is disabled because the endpoint ping failed, edit the web hook's configuration and fix the error. To re-enable the webhook to try again, change the Disabled? section to No and click Update Web hook.
Troubleshoot a webhook error
In some cases, a webhook might activate without issue but still send a webhook 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 the endpoint URL troubleshoot why the webhook failed.