Webhooks

Subscribe a URL to the events you care about. HueChat posts a JSON body for each one and signs it with a secret only you and HueChat know.

Create a subscription

curl -X POST https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/outbound-webhooks \
  -H "Authorization: Bearer $HUECHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "url": "https://your-server.example/webhooks/huechat",
    "events": ["message.created", "conversation.created", "conversation.status_changed", "contact.created", "contact.updated"]
  }'

The response carries the secret once. Store it next to your token.

Events

Event	Fires when
`conversation.created`	A new conversation starts
`conversation.updated`	Labels or custom attributes change
`conversation.status_changed`	Open, pending, resolved
`conversation.assigned`	Assigned to an agent or team
`message.created`	A message is sent or received
`message.updated`	A message is edited or its status changes
`message.delivered`	Delivery confirmed by the channel
`message.read`	Read by the recipient
`message.failed`	Delivery failed
`contact.created`	A contact is added
`contact.updated`	A contact’s profile changes
`agent.assigned`	An agent takes a conversation
`agent.available`	An agent comes online
`automation.triggered`	An automation rule fires
`sla.breached`	An SLA policy is breached
`webhook.test`	You call the test endpoint

What a delivery looks like

Headers:

Header	Example
`X-HueChat-Signature`	`sha256=a1b2c3…`
`X-HueChat-Event`	`message.created`
`X-HueChat-Delivery`	`12345`
`X-HueChat-Timestamp`	`1712345678`
`User-Agent`	`HueChat-Webhook/2.0`

Body:

{
  "event": "message.created",
  "timestamp": "2026-04-05T12:00:00Z",
  "account_id": 3,
  "data": {
    "id": 789,
    "content": "Hi, I need help with my order",
    "message_type": 0,
    "conversation_id": 123,
    "sender": { "id": 456, "name": "Ahmed", "type": "contact" },
    "created_at": 1712345678
  }
}

Verify the signature

Always verify X-HueChat-Signature before acting on a delivery. Anyone who finds your URL can post to it; only HueChat can sign with your secret.

The signature is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with the subscription secret.

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return expected.length === header.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

func verify(body []byte, header, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(body)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(header))
}

Compute the HMAC over the raw bytes, before any JSON parsing or re-serialisation.

Responding

Return 200 within a few seconds and do the real work asynchronously. Any other status counts as a failure and is retried. After 10 consecutive failures the subscription is switched off; re-enable it with a PATCH once your endpoint is healthy. Use X-HueChat-Delivery to drop duplicates, and reject deliveries whose X-HueChat-Timestamp is more than a few minutes old.

Test, inspect, rotate

Action	Call
Send a `webhook.test` event	`POST /api/v2/accounts/{account_id}/outbound-webhooks/{id}/test`
Delivery log with status and response	`GET /api/v2/accounts/{account_id}/outbound-webhooks/{id}/logs`
New secret	`POST /api/v2/accounts/{account_id}/outbound-webhooks/{id}/regenerate-secret`

Account webhooks (v1)

/core/accounts/{account_id}/webhooks is the older subscription list used by the dashboard’s Settings → Integrations page. It posts a flat event object with underscore event names such as message_created and carries no signature header. It still works; for anything new, use the signed subscriptions above.

Get started

Working with the API

Integrate

Create a subscription

Events

What a delivery looks like

Verify the signature

Responding

Test, inspect, rotate

Account webhooks (v1)

​Create a subscription

​Events

​What a delivery looks like

​Verify the signature

​Responding

​Test, inspect, rotate

​Account webhooks (v1)

Create a subscription

Events

What a delivery looks like

Verify the signature

Responding

Test, inspect, rotate

Account webhooks (v1)