Webhooks

A webhook makes AzChat call your server when something happens. It is the alternative to polling the API — faster for you and lighter on the instance.

Creating one

Through the interface, in Settings → Developer → Webhooks, or through the API:

curl --request POST \
  --url 'https://app.azchat.digital/api/v1/accounts/1/webhooks' \
  --header 'api_access_token: SUA_CHAVE_AQUI' \
  --header 'content-type: application/json' \
  --data '{
    "url": "https://seu-servidor.com/azchat",
    "subscriptions": ["message_created", "conversation_created"]
  }'

The url has to be http or https, and it is unique per account: you cannot register the same address twice.

Available events

subscriptions accepts only the values below — anything else fails the request with a 422.

Event	When it fires
conversation_created	A conversation is opened
conversation_updated	Some attribute of the conversation changes
conversation_status_changed	The conversation changes status (open, resolved, pending…)
conversation_typing_on	Someone started typing
conversation_typing_off	Someone stopped typing
message_created	A message is created — inbound or outbound
message_updated	A message is changed
contact_created	A contact is created
contact_updated	A contact is changed
inbox_created	An inbox is created
inbox_updated	An inbox is changed
webwidget_triggered	A visitor opens the chat widget

Scope: account or inbox

A webhook can cover the whole account (account_type, the default) or one specific inbox (inbox_type). Use the inbox scope when the integration only cares about one channel — it saves you processing events you would throw away.

Receiving

AzChat sends a POST with a JSON payload. The body carries the event and the resource involved:

{
  "event": "message_created",
  "id": "12345",
  "content": "Olá, preciso de ajuda",
  "message_type": "incoming",
  "conversation": { "id": 42, "status": "open" },
  "sender": { "id": 7, "name": "Maria" }
}

The exact shape varies by event. Always read event before interpreting the rest, and ignore events you did not explicitly subscribe to — subscriptions can change without your code changing.

Good practices

• Answer fast. Return 200 as soon as you receive it and process in the background. AzChat waits a few seconds at most (WEBHOOK_TIMEOUT, 5s by default) before considering the delivery failed.
• Be idempotent. A delivery can repeat. Use the resource id so you do not process it twice.
• Tolerate new fields. Do not break when you meet an attribute you do not know.
• Validate the origin. The endpoint is exposed to the internet: use a URL with a hard-to-guess secret and check that the payload makes sense before acting on it.

Testing

There is no "resend event" button. To develop, point the webhook at a local tunnel (ngrok, Cloudflare Tunnel) and trigger the event for real — by sending a message to the inbox, for example.