Webhooks
Lo interesante es qué ocurre cuando falla la entrega
Firma, reintentos, orden e idempotencia son todo el contrato. Una integración que resuelve el camino feliz no está terminada; no ha empezado.
- Entrega
- Al menos una vez
- Firmado
- Sobre el cuerpo en bruto
- Reintentos
- Retroceso exponencial
Definition
¿Cómo funcionan los webhooks del pasaporte?
CirculeID envía una llamada de retorno firmada a su endpoint cuando cambia un pasaporte, un evento o una credencial. La entrega es al menos una vez con retroceso exponencial, así que los manejadores deben verificar la firma, tratar los identificadores de entrega repetidos como operaciones nulas y releer el estado actual por la API antes de actuar.
Treat a payload as a notification, not as the record. That single habit removes the entire class of bug where a delayed retry overwrites newer data with older data.
Eventos
A qué puede suscribirse
| Event | Fires when | Typical handler |
|---|---|---|
| passport.created | A passport is issued against an identifier | Print or encode the data carrier |
| passport.updated | The record changes materially | Re-read state; refresh a cached storefront view |
| event.recorded | An EPCIS event is appended to an object | Advance an internal workflow |
| credential.issued | A supplier signs a claim against your product | Clear the compliance gap for that field |
| credential.revoked | An issuer withdraws a claim | Re-open the gap; review anything that relied on it |
| passport.gap_detected | A delegated act change leaves a field unmet | Raise it to the compliance owner |
Verificación
Verifique antes de parsear
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const [ts, signature] = parseHeader(header);
// Reject replays before doing any work.
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${ts}.${rawBody}`) // raw body, exactly as received
.digest();
// Constant-time: a fast reject leaks the signature one byte at a time.
return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}Contrato
Qué garantiza la plataforma
Cargas útiles firmadas
HMAC sobre el cuerpo en bruto con un secreto por endpoint, más una marca temporal.
Entrega al menos una vez
La garantía honesta para un sistema que reintenta. Los manejadores deben ser idempotentes.
Retroceso exponencial
Reintentado durante una ventana amplia, de modo que una caída breve no le cuesta nada.
Versión en cada carga útil
Ignore una entrega que describa una versión que ya ha superado.
Registro de fallos visible
Las entregas fallidas se listan y se pueden reproducir en vez de descartarse en silencio.
Suscripciones acotadas
Suscríbase por tipo de evento, para que un endpoint solo reciba aquello sobre lo que actúa.
Respuestas
Preguntas frecuentes
¿Cómo sé que un webhook vino realmente de CirculeID?
Cada entrega lleva una firma sobre el cuerpo en bruto de la petición y una marca temporal. Verifique la firma contra el secreto de su endpoint antes de parsear, y rechace las entregas cuya marca temporal quede fuera de su ventana de tolerancia. Un endpoint que confía en una carga no verificada es un endpoint al que cualquiera puede enviar.
¿Las entregas están ordenadas?
Por objeto, en la medida de lo posible, pero no dependa de ello. Los reintentos y las condiciones de red hacen que un evento antiguo pueda llegar después de uno más reciente. Cada carga útil lleva la versión de objeto que refleja, así que un manejador debería ignorar una entrega que describe una versión ya superada en lugar de suponer el orden de llegada.
¿Qué ocurre si mi endpoint está caído?
La entrega se reintenta con retroceso exponencial durante una ventana amplia, y el registro de fallos es visible en su cuenta en vez de silencioso. Al expirar la ventana la entrega se marca como fallida; el cambio subyacente sigue siendo consultable por la API, de modo que una caída del webhook causa retraso y no pérdida de datos.
¿Puede entregarse dos veces el mismo evento?
Sí, y debe darlo por supuesto. La entrega al menos una vez es la garantía honesta de cualquier sistema que reintenta. Cada entrega lleva un identificador estable, así que el manejador correcto registra ese identificador y trata una repetición como una operación nula, lo que además hace seguro reproducir una ventana fallida.
¿Debe confiarse en la carga útil de un webhook como registro completo?
Trate la carga útil como una notificación y no como la fuente de verdad. Le indica que algo cambió y le da lo suficiente para decidir si le importa; si actúa, vuelva a leer el estado actual a través de la API. Así, una entrega obsoleta o desordenada no puede escribir datos antiguos en su sistema.
Next step
Apunte el primero a un endpoint de pruebas
Suscríbase en sandbox, rompa su endpoint a propósito y observe el comportamiento de reintento y reproducción antes de depender de él.