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 a web hook's endpoint is developed and hosted on a partner integration platform or an external system managed by your team or a third-party vendor. 

While you can't preview a web hook's payload, you can see example data for each web hook event in our Developer Resources.

Create a webhook

To create a new web hook, click the Configure icon Configure icon on your navigation bar and select Dev Center on the left.

The Configure page shows the Dev Center button highlighted in a marigold emphasis box

Click Web hooks.

The Dev Center page shows the Web Hooks button highlighted in a marigold emphasis box

Click Web hooks on the next page.

Enter the following fields to configure your new web hook:

  • Name this webhook: A name that specifies what the webhook is being used for.
  • When: The event in Greenhouse Recruiting that causes the webhook to activate.
  • Endpoint URL: The URL that will receive the data (must be https).
  • Secret Key: A secret phrase or key used by the receiving endpoint / application 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 app.
  • Error recipient email: The email address that will receive an email notification if the webhook fails. Because there isn't an in-app notification if a webhook fails, we recommend choosing a Greenhouse Recruiting admin to receive the email notification.

If needed, you can configure Advanced Settings should your receiving endpoint require additional Basic or OAuth authentication. You can also configure additional webhook headers and manage the number of retry attempts Greenhouse Recruiting will make if the webhook fails.

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

Click Create web hook to complete the webhook setup.

The Create web hook button is highlighted in a marigold emphasis box

When you create a new web hook, Greenhouse Recruiting will send a ping to your endpoint to verify the connection's working. If the ping is accepted successfully, the endpoint will be created. If the ping is unsuccessful, Greenhouse Recruiting will save the configuration but deactivate the web hook.

Note: If the web hook is deactivated automatically because the endpoint ping failed, scroll to Edit Web Hook and edit the web hook's configuration to fix the error. To re-enable the web hook to try again, change the Disabled? section to No and click Update webhook.

Additional resources