Webhooks
Подписка на события платформы и проверка подписи доставки.
LegalStack доставляет события платформы на ваши HTTPS-эндпойнты. Управление подписками — через API security-service, scope webhooks:write.
Регистрация эндпойнта
POST /api/v1/webhooks HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
{ "url": "https://example.com/hooks/legalstack", "events": ["task.created", "signature.signed"] }В ответе придёт секрет эндпойнта с префиксом whsec_ — сохраните его: он нужен для проверки подписи и показывается один раз. Полный CRUD подписок — в API Reference.
Доставка
Каждое событие приходит POST-запросом с JSON-телом { id, type, teamId, timestamp, data } и четырьмя заголовками:
| Заголовок | Значение |
|---|---|
x-legalstack-signature | подпись v1=<hex> |
x-legalstack-timestamp | unix-время отправки в секундах |
x-legalstack-event-id | идентификатор события |
x-legalstack-event-type | тип события |
Пример реальной доставки (подпись вычислена боевым кодом платформы):
POST /ваш-endpoint HTTP/1.1
content-type: application/json
x-legalstack-signature: v1=29e7075a454efa9d2fdb5b5d15e1e4e93bfd2b635717bda86931b63566f71c16
x-legalstack-timestamp: 1752307200
x-legalstack-event-id: evt_01hzxamp1e
x-legalstack-event-type: task.created
{"id":"evt_01hzxamp1e","type":"task.created","teamId":"team_01hzxamp1e","timestamp":"2026-07-12T08:00:00.000Z","data":{"taskId":"task_01hzxamp1e","teamId":"team_01hzxamp1e","data":{"title":"Проверить договор"}}}Проверка подписи
Подпись — HMAC-SHA256 в hex от строки timestamp + "." + payload, ключ — секрет эндпойнта как обычная UTF-8-строка (без декодирования):
secret = "whsec_2b7e151628aed2a6abf7158809cf4f3c2b7e151628aed2a6abf7158809cf4f3c"
timestamp = "1752307200" // значение заголовка x-legalstack-timestamp
payload = тело запроса (сырые байты)
signature = "v1=" + hex(hmac_sha256(secret, timestamp + "." + payload))
= "v1=29e7075a454efa9d2fdb5b5d15e1e4e93bfd2b635717bda86931b63566f71c16"Сравнивайте подписи константным по времени сравнением и отклоняйте доставки со старым timestamp (например, старше 5 минут) для защиты от replay.
Повторные доставки
Неуспешные доставки (не-2xx ответ) повторяются с экспоненциальной задержкой. Обрабатывайте события идемпотентно по x-legalstack-event-id — одно событие может прийти более одного раза.
Каталог всех типов событий — на странице События.