{
  "id": "evt_01jz8x3m4n5p6q7r8s9t0v1w2x",
  "type": "ping",
  "created_at": "2026-11-04T10:00:00.000Z",
  "workspace_id": "ws_01jz8x3m4n5p6q7r8s9t0v1w2x",
  "company_id": null,
  "data": {}
}

Вебхуки

Ping

Пробное событие (POST …/endpoints//test): проверить, что адрес принимает вебхуки и подпись сходится. Приходит только на этот адрес, в счётчик месяца не идёт. data всегда пуст, company_id — null.

Подпись: заголовки webhook-id, webhook-timestamp, webhook-signature — Standard Webhooks. Проверка: 1) подписанная строка — «webhook-id.webhook-timestamp.тело», тело — байты запроса как пришли, до разбора JSON; 2) ключ — часть секрета после whsec_, раскодированная из base64; 3) HMAC-SHA256 от строки этим ключом, в base64; 4) в webhook-signature одна или несколько подписей через пробел, каждая вида «v1,base64» (при смене секрета сутки приходят две) — должна совпасть хотя бы одна, сравнивать постоянным по времени сравнением; 5) webhook-timestamp — секунды Unix; расхождение с вашими часами больше 5 минут — отклонить. Готовая проверка: new Webhook(secret).verify(rawBody, headers) из npm standardwebhooks.

Доставка: POST JSON на адрес. Успех — любой ответ 2xx за 30 секунд. Иначе — повторы через 5 с, 5 мин, 30 мин, 2 ч, 5 ч, 10 ч, 10 ч, 10 ч, 10 ч, 10 ч, 10 ч, 5 ч: всего 13 попыток, окно 72 ч 35 мин 5 с от первой до последней. После этого событие можно отправить снова вручную (POST …/webhooks/messages//resend). Адрес, который не принимает ничего 5 суток подряд, отключается (enabled: false) — включите его PATCH …/endpoints/ после починки. Доставка «хотя бы раз»: одно событие может прийти дважды — отбрасывайте повторы по id (evt_…), он у повтора тот же. Порядок не гарантируется: события могут прийти не в той последовательности, в какой случились, — сверяйте created_at и читайте актуальное состояние через API. В месячное число бесплатных событий тарифа считаются только события, которые есть кому получить (включённый адрес с подходящим фильтром); сверх него события не отправляются (не копятся и потом не досылаются): сколько не ушло — over_limit в GET …/webhooks/usage.

WEBHOOK

ping

{
  "id": "evt_01jz8x3m4n5p6q7r8s9t0v1w2x",
  "type": "ping",
  "created_at": "2026-11-04T10:00:00.000Z",
  "workspace_id": "ws_01jz8x3m4n5p6q7r8s9t0v1w2x",
  "company_id": null,
  "data": {}
}

Заголовки

webhook-id

string

обязательно

id сообщения (msg_…): один на все попытки доставки этого сообщения; входит в подписанную строку

Пример:

"msg_2xyzExample"

webhook-timestamp

string

обязательно

Время этой попытки, секунды Unix; входит в подписанную строку

Пример:

"1793974568"

webhook-signature

string

обязательно

Подписи через пробел, каждая вида v1,base64 (порядок проверки — в описании события)

Пример:

"v1,kD9WhUZS+K/OigYAsDOosIiagX7cTfjEkMl9fxCJ4GI="

Тело

application/json

Пробное событие (POST …/endpoints/{id}/test): проверить, что адрес принимает вебхуки и подпись сходится. Приходит только на этот адрес, в счётчик месяца не идёт. data всегда пуст, company_id — null.

id

string

обязательно

id события — тот же при повторной доставке: по нему отбрасывайте повторы (evt_…)

Pattern: ^evt_[0-9a-z]{26}$

type

enum<string>

обязательно

Вид события

Доступные опции:

ping

created_at

string<date-time>

обязательно

Когда событие случилось

workspace_id

string

обязательно

Организация (ws_…)

Pattern: ^ws_[0-9a-z]{26}$

company_id

string | null

обязательно

Компания; null — событие организации (например, оплата) (co_…)

Pattern: ^co_[0-9a-z]{26}$

data

object

обязательно

Данные события — только id, суммы, токены, статусы и время, без персональных данных

Ответ

200

Любой ответ 2xx — событие доставлено. Иной ответ или нет ответа за 30 секунд — повтор по расписанию