Webhook endpoints
Configure DALP webhook endpoints, delivery privacy, signing secrets, retries, and chain-of-custody proofs.
Webhook endpoints deliver selected DALP events to an external HTTPS URL. Use them when an integration needs pushed event delivery instead of polling token or account collections.
Endpoint model
Create endpoints with POST /api/v2/webhooks. The request includes:
| Field | Behaviour |
|---|---|
url | Required HTTPS target URL for delivery. |
displayName | Optional label, up to 200 characters. |
subscriptions | Event patterns to deliver. Defaults to *.final, *.retracted, and *.recalled. |
defaultPayloadShape | Must be thin when creating an endpoint. Switch to fat later with a PATCH request and the required field acknowledgement. |
counterSignedReceipts | Optional flag for endpoints that return signed delivery receipts. |
The create and rotate-secret responses reveal the signing secret once. Later reads return endpoint metadata and secret status, not the cleartext signing secret.
Payload privacy
DALP delivers thin payloads by default. Thin payloads omit configured personal-data fields for event types such as identity registration, access-control role changes, asset issuance, compliance freeze recalls, and token transfers.
Create the endpoint as thin first. Switching an endpoint to fat requires a later PATCH /api/v2/webhooks/{id} request with a fatEventsAcknowledgment.fieldsAcknowledged list that covers every additional field implied by the endpoint's subscriptions. DALP rejects the update when the acknowledgement does not match the subscription set.
Delivery operations
| Operation | API route |
|---|---|
| List endpoints | GET /api/v2/webhooks |
| Read endpoint metadata | GET /api/v2/webhooks/{id} |
| Update URL, subscriptions, payload shape, receipt mode, or disabled state | PATCH /api/v2/webhooks/{id} |
| Disable an endpoint | DELETE /api/v2/webhooks/{id} |
| Enqueue a test event | POST /api/v2/webhooks/{id}/test-events |
| List delivery attempts | GET /api/v2/webhooks/{id}/deliveries |
| Read one delivery attempt | GET /api/v2/webhooks/{id}/deliveries/{deliveryId} |
| Retry one delivery event | POST /api/v2/webhooks/{id}/deliveries/{deliveryId}/retries |
| Replay historical events | POST /api/v2/webhooks/{id}/replays |
| Recall an event | POST /api/v2/webhooks/events/{evtId}/recall |
| Get chain-of-custody proof | GET /api/v2/webhooks/events/{evtId}/chain-of-custody |
| Rotate the signing secret | POST /api/v2/webhooks/{id}/rotate-secret |
| Revoke the previous signing secret | POST /api/v2/webhooks/{id}/revoke-previous-secret |
| Read delivery statistics | GET /api/v2/webhooks/stats |
When updating an endpoint URL while deliveries are pending, pass acknowledgePending=true only when you intend DALP to retarget those queued attempts to the new URL.
Secret rotation keeps the previous signing secret valid for a 24-hour overlap. Revoke the previous secret after DALP has observed delivery under the new secret.
Audit proof
DALP records delivery rows with the fields that were redacted during delivery preparation. It also records hop hashes for the prepared payload.
Chain-of-custody proofs return the event's hop hashes, Merkle root, and platform signature. Downstream systems can use that proof to verify what DALP delivered.
Related pages: