Permissions: Basic and above who can manage and configure webhooks

Product tier: Available for all subscription tiers

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.

You can find more information about webhooks in our Developer Resources.

Enable a webhook

To enable a webhook, 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 webhook page, enter the following fields for the web hook:

  • Name this webhook: A name that specifies what the webhook is being used for.
  • 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 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 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.

Note: The default number of retry attempts is 6. You can find more information about our retry policy in our developer documentation here.

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 deactivate the webhook.

Note: If the webhook is deactivated automatically because the endpoint ping failed, scroll to Edit Web Hook and 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 webhook.

To deactivate an active webhoook manually, change the Disabled? section to 'Yes' and click Update webhook. 

To remove an active or deactivated webhook, scroll to Edit Web Hook and select the 'X' icon.

Click 'Yes' in the Are you Sure? pop-up window and the webhook will be removed.

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 with the endpoint URL for more information on the error.