← Вернуться в Dashboard

Документация

На странице

Webhook

Webhook — это HTTP POST, который система отправляет на ваш URL при наступлении события. Эта страница сохраняет контракт Payload v1 для существующих интеграций. Для новых интеграций рекомендуется payload v2; v1 остаётся поддерживаемой версией и не помечена deprecated.

Успешной доставкой считается любой ответ со статусом 200-299.

Формат payload v1

Версия задаётся полем payloadVersion: "1" подписки. Выбранная версия фиксируется вместе с телом в момент постановки события в очередь, поэтому изменение подписки не меняет уже созданные доставки. Переключатель в заголовке меняет только открытую страницу документации.

СобытиеТелоПодпись
Обычное{ type, data }Legacy HMAC, только если указан secret
crm_changeStructured envelope с apiVersion: "v1" и CRM dataAPX-подпись, secret обязателен

Для обычного события тело содержит только type и data:

JSON
{
  "type": "create_message",
  "data": {}
}

Generic v1 не содержит стабильного event ID и occurredAt. Обработчик всё равно должен быть идемпотентным: повторная доставка того же события возможна после сетевой ошибки.

Событие crm_change и в v1 использует structured envelope:

JSON
{
  "id": "811793c8-d361-487b-b3f7-1d59b3fe3fc6",
  "type": "crm.deal.updated",
  "apiVersion": "v1",
  "occurredAt": "2026-08-21T10:30:00.000Z",
  "data": {
    "resourceType": "deal",
    "resourceId": "9ba2e2f7-86b4-4dc1-b2d0-e6423c361d79",
    "externalId": "order-42",
    "action": "updated",
    "version": 7,
    "changedFields": ["amount", "stageUuid"]
  }
}

Для crm_change необходимо выбрать API-приложение со scope чтения соответствующего CRM-ресурса. externalId отсутствует, если выбранное приложение не создавало reference для ресурса.

Подпись (secret)

Обычные события v1

Для обычного события secret опционален. Если он указан, APX Chat добавляет legacy-заголовок:

PLAINTEXT
X-Webhook-Signature: 2a1b... (hex hmac-sha256)

Значение — HMAC-SHA256 от точного raw body без префикса:

TS
import { createHmac, timingSafeEqual } from 'crypto';

function verifySignature(bodyRaw: string, signature: string, secret: string) {
  const expected = createHmac('sha256', secret).update(bodyRaw).digest('hex');
  if (!/^[a-f0-9]{64}$/i.test(signature)) return false;

  return timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex'));
}

CRM change v1

Для crm_change secret обязателен. Используется APX-подпись, как в payload v2:

PLAINTEXT
X-APX-Event-Id: 811793c8-d361-487b-b3f7-1d59b3fe3fc6
X-APX-Event-Timestamp: 1787308200
X-APX-Signature: v1=<hex hmac-sha256>

Подписывается точная строка <timestamp>.<rawBody>. Префикс v1= обозначает версию алгоритма подписи, а не payload. Проверяйте подпись до JSON parsing и ограничивайте допустимый возраст timestamp. Timestamp создаётся заново на каждой попытке, но raw body и event ID остаются прежними.

TS
function verifyApxSignature(bodyRaw: string, timestamp: string, signature: string, secret: string) {
  const expected = createHmac('sha256', secret).update(`${timestamp}.${bodyRaw}`).digest('hex');
  const received = signature.startsWith('v1=') ? signature.slice(3) : '';
  if (!/^[a-f0-9]{64}$/i.test(received)) return false;

  return timingSafeEqual(Buffer.from(received, 'hex'), Buffer.from(expected, 'hex'));
}

Базовая типизация v1

TS
type GenericWebhookEventType =
  | 'create_message'
  | 'edit_message'
  | 'delete_message'
  | 'create_chat'
  | 'close_chat'
  | 'open_chat'
  | 'transfer_chat'
  | 'create_deal'
  | 'move_deal'
  | 'close_deal'
  | 'delete_deal'
  | 'create_pipeline'
  | 'update_pipeline'
  | 'delete_pipeline'
  | 'create_crm_tag'
  | 'update_crm_tag'
  | 'delete_crm_tag'
  | 'create_client'
  | 'update_client';

type WebhookEnvelopeV1<T> = {
  type: GenericWebhookEventType;
  data: T;
};

type CrmChangeWebhookEnvelopeV1 = {
  id: string;
  type: `crm.${string}.${CrmChangeAction}`;
  apiVersion: 'v1';
  occurredAt: string;
  data: {
    resourceType: string;
    resourceId: string | null;
    externalId?: string;
    action: CrmChangeAction;
    version: number | null;
    changedFields: string[];
  };
};

type CrmChangeAction =
  | 'created'
  | 'updated'
  | 'deleted'
  | 'merged'
  | 'anonymized'
  | 'completed'
  | 'failed';

Повторные попытки

  • Повторяются только неуспешные доставки.
  • До 5 попыток всего; перед повторами используются задержки 1m, 2m, 4m, 8m.
  • Обработчик должен быть идемпотентным: сетевой сбой после успешной обработки может привести к повтору.

Список событий

  • Messages: create_message, edit_message, delete_message
  • Deals: create_deal, move_deal, close_deal, delete_deal
  • Pipelines: create_pipeline, update_pipeline, delete_pipeline
  • CRM Tags: create_crm_tag, update_crm_tag, delete_crm_tag
  • Clients: create_client, update_client
  • Chats: create_chat, close_chat, transfer_chat, open_chat
  • CRM API: crm_change

Типы data для обычных событий

create_message

TS
type CreateMessageData = {
  id: string;
  chatUuid: string;
  content: string;
  type: 'system' | 'default';
  senderType: 'client' | 'operator';
  senderUuid: string;
  isUpdated: boolean;
  isSpam: boolean;
  isEmailSent: boolean;
  answerMessageUuid: string | null;
  socialMessageUuid: string | null;
  aiOperatorMeta: any | null;
  createdAt: string;
  updatedAt: string;
};

edit_message

TS
type EditMessageData = CreateMessageData;

delete_message

TS
type DeleteMessageData = CreateMessageData & { deletedAt: string };

create_chat

TS
type CreateChatData = {
  id: string;
  clientUuid: string;
  operatorUuid: string;
  channelUuid: string;
  departmentUuid: string | null;
  transfersUuid: string[];
  status: 'active' | 'closed';
  subject?: string | null;
  createdAt: string;
  updatedAt: string;
};

close_chat

TS
type CloseChatData = CreateChatData & { closedAt: string };

open_chat

TS
type OpenChatData = CreateChatData & { openedAt: string };

transfer_chat

TS
type TransferChatData = CreateChatData & {
  previousOperatorUuid: string;
  newOperatorUuid: string;
  transferredAt: string;
};

create_deal

TS
type CreateDealData = {
  id: string;
  title: string;
  description: string | null;
  amount: number;
  currency: string;
  status: 'active' | 'won' | 'lost' | 'paused';
  priority: 'low' | 'medium' | 'high' | 'urgent';
  source: string;
  expectedCloseDate: string | null;
  actualCloseDate: string | null;
  lossReason: string | null;
  customFields: object | null;
  clientUuid: string | null;
  ownerUuid: string;
  pipelineUuid: string;
  stageUuid: string;
  lostReasonCategoryUuid: string | null;
  chatUuid: string | null;
  rootChanelUuid: string;
  createdAt: string;
  updatedAt: string;
};

delete_deal

TS
type DeleteDealData = CreateDealData & { deletedAt: string };

move_deal

TS
type MoveDealData = CreateDealData & {
  previousStageUuid: string;
  newStageUuid: string;
  movedAt: string;
};

close_deal

TS
type CloseDealData = CreateDealData & { closedAt: string };

create_pipeline

TS
type CreatePipelineData = {
  id: string;
  name: string;
  description: string | null;
  color: string;
  isActive: boolean;
  isDefault: boolean;
  sortOrder: number;
  rootChanelUuid: string;
  createdAt: string;
  updatedAt: string;
};

update_pipeline

TS
type UpdatePipelineData = CreatePipelineData;

delete_pipeline

TS
type DeletePipelineData = CreatePipelineData & { deletedAt: string };

create_crm_tag

TS
type CreateCrmTagData = {
  id: string;
  name: string;
  color: string;
  description: string | null;
  type: 'client' | 'deal' | 'universal';
  isActive: boolean;
  usageCount: number;
  rootChanelUuid: string;
  createdAt: string;
  updatedAt: string;
};

update_crm_tag

TS
type UpdateCrmTagData = CreateCrmTagData;

delete_crm_tag

TS
type DeleteCrmTagData = CreateCrmTagData & { deletedAt: string };

create_client

TS
type CreateClientData = {
  id: string;
  type: 'site' | 'telegram' | 'mail' | 'whatsapp' | 'vk' | 'max';
  rootChanelUuid: string;
  socialId: number | null;
  nameSocial: string | null;
  lastName: string | null;
  name: string | null;
  email: string[];
  avatarUrl: string | null;
  phone: string[];
  ip: string[];
  city: string[];
  isOnline: boolean;
  isContactRequestPending: boolean;
  otherFields: object | null;
  lastVisit: string;
  createdAt: string;
  updatedAt: string;
};

update_client

TS
type UpdateClientData = CreateClientData;

Поля в data могут расширяться обратно-совместимо. Не завязывайтесь на строго фиксированный набор полей без необходимости.