Webhooks

Updated September 7, 2026

On this page

Webhooks push events to your URL in real time: new conversations, messages, assignments, closings and ratings. This is the backbone of CRM, Slack and internal-system integrations.

Диалог

Чатва

Вебхук

message:new

Битрикс24

лид + переписка

Event in Chatva → POST to your URL → action in your system

Field	Type	Description
url	string, required	HTTPS handler address
events	array, required	Event list: message:new, conversation:new, conversation:update

Request example

curl -X POST https://api.chatva.app/v1/webhooks \
  -H "Authorization: Bearer ch_live_9f3ka2" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://crm.yourco.ru/hooks/chatva", "events": ["message:new", "conversation:new"]}'

Events

Event	When it fires
message:new	A new message in any conversation — from a client, operator or bot
conversation:new	A new conversation is created in any channel
conversation:update	Conversation status, assignee, department, tags or rating changed

Payload format

Payload example

{
  "type": "message:new",
  "payload": {
    "conversation": {
      "id": "cv_018f3a",
      "channel": "telegram",
      "client": "Kira Meshcheryakova"
    },
    "message": {
      "id": "m_5521",
      "from": "client",
      "text": "Hello!",
      "createdAt": "2026-09-07T12:00:00Z"
    }
  }
}

Delivery and retries

Respond 2xx within 5 seconds — otherwise the event is retried up to three times with backoff.
Every request is signed with the X-Chatva-Signature header: HMAC-SHA256 of the body using the webhook secret. Verify it to reject forged requests.
Event order is not guaranteed — rely on the createdAt field inside the payload.
Inactive webhooks (10 consecutive failed deliveries) are disabled and flagged in the dashboard.

Webhooks

POST /webhooks — create a subscription

Events

Payload format

Delivery and retries