Using webhooks

Webhooks are a system that allows you to be proactively notified when users take a particular action in the CRM. You can create and manage them using the API functions listed here. This page explains a bit about how they work, as well as a full code example of registering, triggering, and parsing the body of a webhook.

Add a new webhook using the Api call CreateWebhook. Note webhooks cannot be updated once created; you must delete the old one and create another. Here are the parameters the function takes:

EndpointUrl

• MUST be HTTPS.
• While setting up the hook, we will send a POST to the endpoint with a header X-Hook-Secret.
  • The endpoint MUST send a response with an identical header.
  • This secret will also be used to sign payloads, as described later, so you should save it.

WebhookScope

• Set to “User” to only report events by the current user.
• Set to “Account” to report events taken by any user on the account.

Events

• An array of events that will trigger a webhook send. See the next section for details.

Please note this system is new, and we currently only support webhooks for a limited number of CRM events. We are planning to expand this list; you can contact us if there is a particular event you would like to see added.

You will only receive webhooks for objects that you have permission to see. Payloads will always include UserId of the user who triggered the event, as well as TriggeringEvent, the name of the event that caused the hook to fire.

Contact.Create

• trigger: when a new contact is created in the CRM.
• payload:

{
    Contacts: [ 
        { ContactId, ... }, 
        ... 
    ]
}

For full contact format, see GetContacts.

Event.Create, Event.Update

• trigger: when an event is created or updated in the CRM.
• payload:

{
    Event: { EventId, ... }
}

For full event format, see GetEvent.

Event.Delete

• trigger: when an event is deleted in the CRM. Only includes ID of deleted event.
• payload:

{ EventId }

GroupMembership.Create

• trigger: when a contact is added to a group in the CRM.
• payload:

{
    Group: { GroupId, ... }
    Contacts: [
        { ContactId, ... },
        ...
    ]
}

For full group format, see GetGroup. For full contact format, see GetContacts.

PipelineItemStatus.Create, PipelineItemStatus.Update

• trigger: when a pipeline item is created, or when its status changes.
• payload:

{
    PipelineItems: [
        { PipelineItemId, ... },
        ...
    ]
}

For full pipeline item format, see GetPipelineItem.

Once a webhook has been created, any triggered event in the CRM will send a POST to the provided URL. It will include the header X-Hook-Signature. This is a SHA-256 HMAC hash of the body, using the X-Hook-Secret from the original handshake as the key. You can use it to verify the legitimacy of the payload.

We will retry failed sends with exponential backoff. The send MUST return a good HTTP code (<300) to be considered a success. If we do not succeed after several retries, we will disable the webhook and notify you via email.

GetWebhook will return LastSendDate, the date of the last successful send.

Here is a full example of registering, triggering, and parsing the body of a webhook.