Eventos de webhook y verificación de firma

Crear un webhook

1. Abra Settings, Webhooks (propietarios y administradores).
2. Introduzca la dirección HTTPS de su receptor.
3. Elija los eventos que necesita; sin selección recibe todos.
4. Introduzca un secreto de firma de al menos 16 caracteres, o déjelo vacío para que DPP Shield genere uno. Cópielo ahora: solo se muestra una vez.
5. Vigile el registro de entregas con los primeros eventos reales.

Cómo es una entrega

Cada entrega es un POST HTTP con Content-Type application/json y el cuerpo {"event": "dpp.published", "payload": {…}, "deliveredAt": "2026-10-08T09:30:00.000Z"}. El payload depende del evento, así que lea primero el nombre del evento. Las entregas de ciclo de vida y EPCIS llevan el evento de objeto EPCIS estándar dentro del payload.

Verificar la firma

En Node.js el valor esperado es "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"). Analizar y volver a serializar el JSON cambia los bytes y rompe la comparación: firme siempre el cuerpo sin procesar. Un reintento o una repetición pueden entregar el mismo evento otra vez: haga su procesamiento idempotente, por ejemplo por pasaporte y versión.

1. Lea el cuerpo sin procesar de la solicitud antes de analizar el JSON.
2. Calcule el HMAC-SHA256 de ese cuerpo con su secreto de firma y codifíquelo en hexadecimal.
3. Compare sha256= seguido de su resultado con la cabecera x-dpp-signature mediante una comparación de tiempo constante.
4. Rechace la solicitud si difieren; si no, responda 2xx y procese el evento.

Reintentos, registro de entregas y repetición

Una entrega fallida - error de red o respuesta distinta de 2xx - se reintenta hasta cinco veces con espera exponencial desde un segundo. Cada intento se registra con su código de estado y su error. Tras arreglar el receptor, repita una entrega guardada desde el registro; se pone en cola como una entrega nueva. Cambiar la dirección o rotar el secreto mantiene las entregas firmadas, y eliminar un webhook elimina también su historial.

Catálogo de eventos

Suscriba un receptor a los eventos que necesita; el nombre del evento es el primer campo de cada entrega.

Eventos

• dpp.created - se creó un pasaporte.
• dpp.updated - se escribió una nueva versión inmutable del pasaporte.
• dpp.published - se publicó un pasaporte en la vista pública.
• dpp.event_recorded - un evento de ciclo de vida (reparado, transferido, reciclado, inspeccionado…).
• epcis.event - el evento de objeto GS1 EPCIS 2.0 de un evento de ciclo de vida.
• compliance.alert - una validación produjo hallazgos de incumplimiento.
• supplier.responded - un proveedor respondió a una solicitud a través del portal.
• document.expiring - un documento del repositorio se acerca a su fecha de caducidad.
• recall.issued - se retiró un pasaporte; sus credenciales se revocan y la página pública indica la retirada.
• dpp.reinstated - un pasaporte retirado o archivado se reabrió para corregirlo.
• dpp.archived - se dio de baja un pasaporte; su última versión publicada sigue legible.
• channel.retraction_required - un pasaporte retirado debe quitarse de cada canal al que se envió.
• channel.feed_ready - se generó y envió un feed de marketplace o tienda.
• dpp.remanufactured - se emitió un pasaporte derivado para un artículo remanufacturado o reacondicionado.
• dpp.split y dpp.merged - un pasaporte se dividió en artículos serializados, o varios se consolidaron.
• dpp.credential_issued - se firmó una credencial verificable para un pasaporte publicado.
• regulation.pack_changed - se capturó un paquete normativo con nueva versión, estado o reglas.
• audit.chain_head - el anclaje diario de la cadena de hash de auditoría de la organización; consérvelo para verificar el registro más adelante.

Suscripciones EPCIS

Una suscripción EPCIS en Settings, EPCIS es un webhook con un filtro permanente por tipos de evento, pasos de negocio, disposiciones, productos, categorías o pasaportes. Sus entregas usan el evento epcis.event, el mismo sobre y la misma firma.