Skip to main content

Webhooks

Webhooks let your own systems react automatically when a Digital Product Passport changes state. Instead of polling Traceable, you register an endpoint URL and Traceable sends it a signed HTTPS notification whenever a subscribed event occurs, for example when a passport is published or withdrawn.

You manage webhook endpoints in Settings → Webhooks.

Every event is signed with a per-endpoint signing secret so your systems can verify that the notification genuinely came from Traceable.

The endpoints table​

The Webhooks page lists the endpoints you have registered. Each row shows:

ColumnWhat it shows
NameThe label you gave the endpoint
URLThe HTTPS address events are delivered to
EventsThe event types this endpoint is subscribed to
Statusactive or disabled
Modelive or test
CreatedWhen the endpoint was registered
ActionsView deliveries, enable/disable, rotate secret, delete

Endpoints created here in the portal are always live mode. Sandbox (test mode) endpoints are managed through the Integration API using a test key, not through this page.

Adding an endpoint​

  1. Navigate to Settings → Webhooks.
  2. Click Add Endpoint.
  3. Enter a Name that identifies the receiving system (for example ERP integration).
  4. Enter the Endpoint URL. It must be an https:// address. Private and internal network addresses are rejected.
  5. Select one or more Events to subscribe to.
  6. Click Create Endpoint.

The button stays disabled until the name, a valid HTTPS URL, and at least one event are all provided.

Events you can subscribe to​

EventFires when
DPP publishedA Digital Product Passport is published
DPP withdrawnA published passport is withdrawn
Document verifiedA compliance document is verified
Submission receivedA passport is submitted for review

The signing secret​

When you create an endpoint, Traceable shows its signing secret once, in a dialog.

  • The secret is shown only at creation time (and again when you rotate it). It cannot be retrieved afterwards.
  • Copy it immediately and store it in your secrets manager.
  • If it is lost, rotate the endpoint to generate a new one.

Use the signing secret to verify the Webhook-Signature header on every event you receive. Any request that does not carry a valid signature must be rejected. For the exact verification steps, see the Integration API: Authentication reference.

Store the secret now

The signing secret is displayed only once. After you close the dialog it cannot be shown again, only rotated.

Viewing deliveries​

Click the deliveries action on an endpoint row to open its delivery log. It shows the 50 most recent delivery attempts, with:

  • The event type
  • The delivery status: delivered, pending, failed, or dead_letter
  • The number of attempts
  • The last result (the HTTP status code returned by your endpoint, or the last error)
  • When the delivery was created

Failed deliveries are retried automatically. A delivery that keeps failing is eventually moved to dead_letter, from where you can re-queue it manually with Redeliver. A re-queued delivery is retried within the next few minutes.

Enabling and disabling an endpoint​

Use the Enable / Disable action on a row to switch an endpoint on or off. A disabled endpoint stops receiving events but keeps its configuration and delivery history, so you can re-enable it later without recreating it.

Rotating the signing secret​

Rotation replaces an endpoint's signing secret with a new one. Do this periodically, or whenever you suspect the secret may have been exposed.

  1. Click the rotate action on the endpoint row.
  2. Confirm the rotation.
  3. Copy the new secret from the dialog and update your receiver.

The old secret stops working immediately when you rotate, so update your receiving system right away or deliveries will start failing signature verification.

Deleting an endpoint​

Click the delete action on a row and confirm. The endpoint stops receiving events immediately and its delivery history is removed. This cannot be undone.

How to verify a delivery​

Each delivery is a POST with a canonical JSON body and two headers:

  • Webhook-Signature: t=<unix_seconds>,v1=<hex>
  • Webhook-Id: <delivery_id> (use this as your retry idempotency key)

Recompute the signature as an HMAC-SHA256 of <t>.<raw_body> keyed with your signing secret, and compare it to v1 using a timing-safe comparison. Reject the delivery if the timestamp t is more than 300 seconds away from the current time. Full code and payload details are in the Integration API overview.