Webhooks help you provide with real-time information. If any changes happen in the website like a user filled a form or had a conversation with an agent, each and every piece of information will be delivered to you as it happens. This makes the process more efficient, unlike other APIs where you need to call for data frequently in order to get it real-time.
Note: Webhooks feature is available only for workspaces on our Premium plans.
Setting up webhooks
- Navigate to Settings > API & Webhooks > Webhooks page
- Click Create webhook button
- Give your webhook a name, and choose a topic from the list
- On the webbook editor, choose HTTP method and enter the Webhook URL
- Click Save Webhook
- To set your webhook live, turn the switch ON
For Advanced Users
You can additionally pass custom header and body parameters as needed as shown below.
Webhooks supported topics
You can retrieve the data in JSON format. Webhooks are available for the following topics:
- User created - When a new user gets created
- Lead created - When a new lead gets created
- User deleted - When an existing user is deleted
- Lead deleted - When an existing lead is deleted
- Contact created - When a new contact is created
- Contact tagged - When a contact gets tagged
- Contact untagged - When a contact gets untagged
- Custom property value updated - When a custom property value has been updated
- Contact email updated - When the contact email is updated
- Lead submitted email - When a lead submits an email
- Contact unsubscribed from emails - When a contact unsubscribed emails
- Contact initiated conversation - When we receive a new message from a contact
- Conversation assigned - When a conversation gets assigned to a teammate
- Conversation opened - When a conversation is opened
- Conversation closed - When a conversation is closed
- New message received - When a contact sends a message in chat
- Teammate replied - When a teammate replied in chat
- Conversation rating left - When a contact leaves a satisfaction rating
- Note added - When a teammate add a note to the conversation
- Contact subscribed to campaign - When the contact subscribed for a campaign
- Contact unsubscribed from campaign - When the contact unsubscribed for a campaign
- Contact performed an event - When a contact performed an event
- Contact submitted form - When a contact submits a form
- New page visited - When there is a new page visit
- Meeting scheduled - When a meeting is scheduled
- Meeting cancelled - When a meeting is canceled
- Meeting rescheduled - When a meeting is rescheduled
Handling Notification
When you setup a subscription you will receive notifications on your chosen topics. How you handle those notifications, i.e. the HTTP status code returned, will determine the subsequent state of that subscription. Please see below for a list of how a subscription will respond to these status codes.
| Response code | Description | Action |
| 2xx - Success | Timeout in 10 seconds | |
| 410 - Gone | Resource no longer available | The webhook will be disabled |
| 4xx, 5xx | Client or service error | 1st retry in 5 Minutes. 2nd retry in 1 Hour. 3rd retry in 3 Hours |
Validation of webhooks events
Only for the Gist users who want signed webhooks, this function will be available. They need to enter the webhook secret in the required text box present in the webhook configuration page. Leave it blank if you don’t want it. We do this so that you can verify the notification came from Gist by decoding the signature.
The HTTP request will contain an X-Hub-Signature header which contains the SHA1 signature of the request payload, using the webhook secret as the key, and prefixed with sha1=. Your callback endpoint can verify this signature to validate the integrity and origin of the payload
Please note that the calculation is made on the escaped Unicode version of the payload, with lower case hex digits. For example, the string äöå will be escaped to \u00e4\u00f6\u00e5. The calculation also escapes / to \/, < to \u003C, % to \u0025 and @ to \u0040. If you just calculate against the decoded bytes, you will end up with a different signature.
Need Help?
If you have any further questions, please start a Live Chat. Just "Click" on the Chat Icon in the lower right corner to talk with our support team.