How to Create a Webhook Subscription

Have your CRM send events to an address of your own, and check that each delivery arrived.

A webhook is a message your CRM sends to a web address you control when something happens. The Webhooks page under Developer in Settings is where you set one up. The page describes itself as outbound webhook subscriptions for your events. This guide walks through creating a subscription, saving its signing secret, testing it and following up on failures.

1. 1

   Open Webhooks

   Open Settings, go to Developer and choose Webhooks. If you do not see Developer in Settings, your role does not include it, so ask an admin. The Developer group also holds Ingest Keys and Partners. If your plan does not include this page, it shows a message and a link to plans instead of the list.
2. 2

   Choose Create Subscription

   Choose + Create Subscription at the top right. The Create Webhook Subscription window opens. If you have none yet, the page says that no webhook subscriptions exist yet and that you can create one to receive events at your own endpoint.
3. 3

   Fill in Name and Endpoint URL

   Type a Name, for example Zapier integration. It is required, and the window says so if you leave it empty. Then type the Endpoint URL, the web address that should receive the events. It is required too, and the hint shows the shape of an address.
4. 4

   Choose Event Types

   The window lists the event types you can tick, each with a one-line description, for example an inbound email received and a test event. Tick the ones you want. If you leave all of them unticked, the subscription receives every event type.
5. 5

   Add a Description

   The Description box is optional. Use it to note what the subscription is for.
6. 6

   Create the subscription

   Choose Create Subscription. The button reads Creating while it saves. Choose Cancel to close the window without saving.
7. 7

   Save the signing secret

   A window called Save Your Signing Secret Now opens and shows the secret together with a note. It is shown this one time. Choose Copy to Clipboard, keep the secret somewhere safe, tick that you have saved it in a secure location, and then choose Done. Done stays off until you tick the box.
8. 8

   Send a test event

   The new subscription appears under Active, with its name, its address, the events it receives, which reads All events when none were ticked, and the dates of creation and last delivery. Choose Send test event. The page tells you how many deliveries were dispatched and points you to the recent deliveries below.
9. 9

   View recent deliveries

   Choose View recent deliveries. Each delivery shows its event, its status and the time. If nothing has been sent yet, the panel says that there are no deliveries yet. Choose Hide recent deliveries to close it.
10. 10

    Edit, rotate the secret or delete

    Choose Edit to change the name, the address, the event types or the description. Choose Rotate Secret to get a new signing secret, which is shown once in the same way. Choose Delete and then Confirm to remove the subscription, or Cancel to keep it.
11. 11

    Check the Dead Letter Queue

    At the bottom of the page, the Dead Letter Queue lists deliveries that failed every attempt, with the event, the number of attempts used, the reason for the failure and the date. Choose Retry to try one again; the page tells you whether it was delivered or is still failing. Choose Resolve, add a note if you like and confirm that you will not retry it. When nothing has failed, the page says there are no unresolved failed deliveries.

A few things worth knowing

A subscription that has recently failed shows how many recent failures it has, next to its status. Subscriptions are grouped as Active and Inactive, so you can find the ones that are switched off.

This guide covers the Webhooks page. It does not describe how to verify a message with the signing secret or what an event contains, because the page does not show that. To let another tool send leads into your CRM, the guide on creating a lead capture key covers the other page in Developer, and the guide on creating a custom role shows how to decide who can reach settings like these.