Webhooks

Receive real-time HTTP notifications when events occur in your CRM workspace.

Supported Events

Managing Webhooks

Webhooks are managed through the Settings → API Keys page in the CRM app. Each webhook requires:

• A name
• An HTTPS endpoint URL
• One or more event types to subscribe to
• One or more workspaces to receive events from
• For Telegram events, all accessible accounts or a selected set of accounts

When you create a webhook, a signing secret is generated and shown once. Save it securely — you'll need it to verify webhook signatures.

Payload Format

All webhook payloads are sent as HTTP POST requests with Content-Type: application/json.

Headers

Event payload

For contact.created and contact.deleted:

{
  "eventId": "evt_abc123_wh456",
  "eventType": "contact.created",
  "eventDate": "2026-03-24T12:00:00.000Z",
  "workspaceId": "workspace-id",
  "data": {
    "id": "contact-id",
    "fullName": "John Doe",
    "email": "john@example.com",
    "createdAt": "2026-03-24T12:00:00.000Z",
    "updatedAt": "2026-03-24T12:00:00.000Z"
  }
}

For contact.updated, both current and previous state are included:

{
  "eventId": "evt_abc123_wh456",
  "eventType": "contact.updated",
  "eventDate": "2026-03-24T12:00:00.000Z",
  "workspaceId": "workspace-id",
  "data": {
    "id": "contact-id",
    "fullName": "Jane Doe"
  },
  "previousData": {
    "id": "contact-id",
    "fullName": "John Doe"
  }
}

For contact.deleted, data contains the full contact snapshot before deletion.

Telegram update payload

Telegram events use the generated TL update name in eventType. Their data field contains the account, the raw Telegram update, and the peer context required to resolve referenced users and chats:

{
  "eventId": "evt_abc123",
  "eventType": "telegram.updateNewMessage",
  "eventDate": "2026-08-10T12:00:00.000Z",
  "workspaceId": "workspace-id",
  "data": {
    "workspaceId": "workspace-id",
    "accountId": "telegram-account-id",
    "sourceLayer": 228,
    "emittedAt": 1786363200000,
    "update": {
      "_": "updateNewMessage",
      "message": { "_": "message", "id": 123 }
    },
    "users": [],
    "chats": [],
    "hasMin": false
  }
}

The complete list of specific Telegram update event names is available in the API reference. Use telegram.* when the endpoint should receive every generated Telegram update type.

Verifying Signatures

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with your webhook's signing secret.

import { createHmac } from "crypto";

const signature = createHmac("sha256", signingSecret).update(rawBody).digest("hex");

const isValid = signature === req.headers["x-webhook-signature"];

Always verify signatures before processing webhook payloads to ensure they originate from CRM Chat.

Failure Policy

If your webhook endpoint is unavailable or returns a non-2xx status code:

• Each delivery is attempted up to 10 times with exponential backoff (starting at 5 minutes, doubling each time) over approximately 24 hours
• If no successful delivery occurs within 3 days, the webhook is automatically disabled
• You'll receive a Telegram notification when a webhook is disabled
• You can re-enable disabled webhooks from Settings → API Keys

Timeout

Webhook deliveries have a 20-second timeout. Ensure your endpoint responds within this window.