Вебхуки применения

В режиме вебхука (applyMode = 'webhook') завершённый импорт доставляется на ваш бэкенд как HTTP-POST — подписанный HMAC, надёжно повторяемый и записанный в журнал аудита доставки.

Зарегистрируйте свой endpoint

Зарегистрируйте URL один раз; ответ содержит секрет подписи ровно один раз — сохраните его. Ротация выдаёт его заново тем же способом.

POST /api/import/v1/webhooks
content-type: application/json

{ "url": "https://api.your-app.example/mildport/apply" }

Запрос

POST /your/apply-endpoint
x-import-event: import.apply
x-import-delivery-id: dlv_4f2…
x-import-timestamp: 1717000000
x-import-signature: t=…,v1=hmac_sha256(body)…
content-type: application/json

{
  "event": "import.apply",
  "deliveryId": "dlv_4f2…",
  "tenantId": "tnt_…",
  "recordId": "rec_…",
  "action": "submit",
  "rowCount": 128,
  "mapping": { "Email": "person.email", "First name": "person.firstName" },
  "rows": [{ "person.email": "[email protected]", "person.firstName": "Ada" }],
  "occurredAt": "2026-07-12T00:00:00.000Z"
}

meta (контекст хоста), entities и links (разрешённый граф ссылок) появляются, когда импорт их использовал.

Проверьте подпись

Вычислите HMAC-SHA256 по сырому телу запроса с вашим секретом доставки и сравните его за постоянное время со значением v1 в x-import-signature. Значение t= — это подписанная метка времени; отклоняйте доставки, чья метка времени слишком стара, чтобы ослабить атаки повтора.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map(kv => kv.split('=')));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const got = Buffer.from(parts.v1 ?? '', 'hex');
  const exp = Buffer.from(expected, 'hex');
  return got.length === exp.length && timingSafeEqual(got, exp);
}

Повторы и идемпотентность

Доставки повторяются с backoff, пока ваш endpoint не вернёт 2xx. Используйте x-import-delivery-id (или recordId) для дедупликации — один и тот же импорт может быть доставлен более одного раза.