Working with webhooks

Use webhooks to receive API updates on when things happen in your Gist workspace.

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

  1. Navigate to Settings > API & Webhooks > Webhooks page
  2. Click Create webhook button
  3. Give your webhook a name, and choose a topic from the list
  4. On the webbook editor, choose HTTP method and enter the Webhook URL
  5. Click Save Webhook
  6. 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:

  1. User created - When a new user gets created
  2. Lead created - When a new lead gets created
  3. User deleted - When an existing user is deleted
  4. Lead deleted - When an existing lead is deleted
  5. Contact created - When a new contact is created
  6. Contact tagged - When a contact gets tagged
  7. Contact untagged - When a contact gets untagged
  8. Custom property value updated - When a custom property value has been updated
  9. Contact email updated - When the contact email is updated
  10. Lead submitted email - When a lead submits an email
  11. Contact unsubscribed from emails - When a contact unsubscribed emails
  12. Contact initiated conversation - When we receive a new message from a contact
  13. Conversation assigned - When a conversation gets assigned to a teammate
  14. Conversation opened - When a conversation is opened
  15. Conversation closed - When a conversation is closed
  16. New message received - When a contact sends a message in chat
  17. Teammate replied - When a teammate replied in chat
  18. Conversation rating left - When a contact leaves a satisfaction rating
  19. Note added - When a teammate add a note to the conversation
  20. Contact subscribed to campaign - When the contact subscribed for a campaign
  21. Contact unsubscribed from campaign - When the contact unsubscribed for a campaign
  22. Contact performed an event - When a contact performed an event
  23. Contact submitted form - When a contact submits a form
  24. New page visited - When there is a new page visit
  25. Meeting scheduled - When a meeting is scheduled
  26. Meeting cancelled - When a meeting is canceled
  27. 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
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.

Was this article helpful?