Chatva
API: Webhooks

Webhooks

Updated September 7, 2026

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

POST /webhooks — create a subscription

FieldTypeDescription
urlstring, requiredHTTPS handler address
eventsarray, requiredEvent 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

EventWhen it fires
message:newA new message in any conversation — from a client, operator or bot
conversation:newA new conversation is created in any channel
conversation:updateConversation 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.
← Contacts →Limits and errors