Webhook events and signature verification

Create a webhook

1. Open Settings, Webhooks (owners and administrators).
2. Enter the HTTPS address of your receiver.
3. Choose the events it needs; with none selected it receives every event.
4. Enter a signing secret of at least 16 characters, or leave it empty and DPP Shield generates one. Copy it now: it is shown once.
5. Watch the delivery log for the first real events.

What a delivery looks like

Each delivery is an HTTP POST with Content-Type application/json and the body {"event": "dpp.published", "payload": {…}, "deliveredAt": "2026-10-08T09:30:00.000Z"}. The payload depends on the event, so read the event name first. Lifecycle and EPCIS deliveries carry the standard EPCIS object event inside the payload.

Verify the signature

In Node.js the expected value is "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"). Parsing and re-serializing the JSON changes the bytes and breaks the comparison, so always sign the raw body. A retry or a replay can deliver the same event again: make your processing idempotent, for example by passport and version.

1. Read the raw request body before any JSON parsing.
2. Compute the HMAC-SHA256 of that raw body with your signing secret and hex-encode it.
3. Compare sha256= followed by your result with the x-dpp-signature header, using a constant-time comparison.
4. Reject the request if they differ; otherwise answer 2xx and process the event.

Retries, the delivery log and replay

A delivery that fails - a network error or a non-2xx answer - is retried up to five times with exponential backoff starting at one second. Every attempt is logged with its status code and error. After fixing the endpoint, replay a stored delivery from the log; it is queued as a fresh delivery. Changing the address or rotating the secret keeps deliveries signed, and deleting a webhook also deletes its delivery history.

Event catalogue

Subscribe a receiver to the events it needs; the event name is the first field of every delivery.

Events

• dpp.created - a passport record was created.
• dpp.updated - a new immutable passport version was written.
• dpp.published - a passport was published to the public view.
• dpp.event_recorded - a lifecycle event (repaired, transferred, recycled, inspected…).
• epcis.event - the GS1 EPCIS 2.0 object event for a lifecycle event.
• compliance.alert - a validation run produced non-compliant findings.
• supplier.responded - a supplier answered a data request through the portal.
• document.expiring - a vault document is approaching its expiry date.
• recall.issued - a passport was recalled; its credentials are revoked and the public page states the recall.
• dpp.reinstated - a recalled or archived passport was opened for correction.
• dpp.archived - a passport was retired; its last published release stays readable.
• channel.retraction_required - a recalled passport must be taken down from every channel it was sent to.
• channel.feed_ready - a marketplace or storefront feed was built and dispatched.
• dpp.remanufactured - a derived passport was issued for a remanufactured or refurbished item.
• dpp.split and dpp.merged - a passport was split into serialized items, or several were consolidated.
• dpp.credential_issued - a verifiable credential was signed for a published passport.
• regulation.pack_changed - a regulation pack was captured with a new version, status or rule set.
• audit.chain_head - the daily anchor of the organization's audit hash chain; keep it to verify the trail later.

EPCIS subscriptions

An EPCIS subscription under Settings, EPCIS is a webhook with a standing filter on event types, business steps, dispositions, products, categories or passports. Its deliveries use the event epcis.event, the same envelope and the same signature.