This article shows you how to get HueChat to push events to your server, so your CRM, ticketing tool or automation reacts the moment a message arrives. Webhooks are included from the Growth plan.
HueChat has two webhook systems:
/api/v2/accounts/{account_id}/outbound-webhooks. Each delivery carries an HMAC-SHA256 signature, a delivery id and a timestamp, and failed deliveries are retried.message_created and carry no signature header. They still work, but use signed subscriptions for anything new.webhooks:write scope, or use your personal access token.POST to /api/v2/accounts/{account_id}/outbound-webhooks with a name, your HTTPS url and the list of events you want.secret from the response. It is shown once and you need it to verify deliveries.webhook.test event and confirm your server answers 200.The full request and response examples are in the Developer Hub at https://developers.huechat.ai.
| Event | Fires when |
|---|---|
message.created |
A message is sent or received |
message.delivered, message.read, message.failed |
The channel confirms delivery, read or failure |
conversation.created |
A new conversation starts |
conversation.status_changed |
Open, pending or resolved changes |
conversation.assigned, agent.assigned |
A conversation is assigned to an agent or team |
contact.created, contact.updated |
A contact is added or changed |
automation.triggered |
An automation rule fires |
sla.breached |
An SLA policy is breached |
Each delivery is a JSON POST with the headers X-HueChat-Event, X-HueChat-Delivery, X-HueChat-Timestamp and X-HueChat-Signature. The body has the event name, a timestamp, your account_id and a data object with the message, conversation or contact.
Always verify before you act on a delivery. Anyone who finds your URL can post to it; only HueChat can sign with your secret.
sha256=<hex digest> with the X-HueChat-Signature header using a constant-time comparison.X-HueChat-Timestamp is more than a few minutes old.Code samples for Node.js, Python and Go are in the Developer Hub.
200 within a few seconds and do the real work in a background job.PATCH.X-HueChat-Delivery to drop duplicates, because retries can deliver the same event twice.The delivery log endpoint shows each attempt with its status and your server's response, and the regenerate-secret endpoint issues a new secret when you need to rotate it.
Screenshot: The Webhooks page in Settings with an existing subscription and the Add Webhook button.