Webhooks de aplicación

En modo webhook (applyMode = 'webhook'), una importación completada se entrega a tu backend como un POST HTTP — firmado con HMAC, reintentado de forma duradera y registrado en un registro de auditoría de entrega.

La solicitud

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

{
  "event": "import.applied",
  "recordId": "rec_…",
  "action": "submit",
  "rowCount": 128,
  "mapping": { "Email": "person.email", "First name": "person.firstName" },
  "rows": [{ "person.email": "[email protected]", "person.firstName": "Ada" }]
}

Verifica la firma

Calcula un HMAC-SHA256 sobre el cuerpo bruto de la solicitud usando tu secreto de entrega, y compáralo en tiempo constante con el valor v1 de x-import-signature. El valor t= es la marca de tiempo firmada — rechaza las entregas cuya marca de tiempo sea demasiado antigua para mitigar los ataques de repetición.

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);
}

Verifica antes de confiar

Verifica siempre la firma y la marca de tiempo antes de actuar sobre una entrega, y lee los bytes brutos del cuerpo — volver a serializar el JSON primero cambiará la firma.

Reintentos e idempotencia

Las entregas se reintentan con backoff hasta que tu endpoint devuelve 2xx. Usa x-import-delivery-id (o recordId) para deduplicar — la misma importación puede entregarse más de una vez.