Webhooks
Webhooks are how DiligenceID tells your systems that something happened, without you polling.
Subscriptions are managed with the webhooks.manage scope, or by an administrator.
Delivery
Every delivery is an HTTPS POST carrying:
| Part | Purpose |
|---|---|
| Event id | Unique per event |
| Delivery id | Unique per delivery attempt |
| Timestamp | When the event occurred |
| Type | e.g. credential.revoked |
| Tenant | Which tenant the event belongs to |
| Correlation reference | Ties the event to the API call that caused it |
| Payload | The event body |
| Signature | HMAC over the payload |
Verifying the signature
Always verify before acting. Compute the HMAC of the raw request body with your subscription's signing secret and compare it to the signature header in constant time. Reject anything that does not match.
Verify against the raw body bytes, before any JSON parsing or re-serialisation — re-serialising changes the bytes and the signature will not match.
Reject events whose timestamp is outside a tolerance you choose (five minutes is typical), so a captured delivery cannot be replayed at you later.
Responding
Return 2xx promptly and do the work asynchronously — a slow endpoint is treated as a failed delivery.
Failed deliveries are retried with exponential backoff and eventually dead-lettered. Delivery history is available and a delivery can be replayed manually. Make your handler idempotent: use the event id to discard one you have already processed.
Endpoint requirements
- HTTPS is required in production.
- Localhost and private network addresses are refused by default. DiligenceID validates the destination before every delivery and does not follow redirects, so a receiver cannot redirect a delivery into an internal network.
Rotating a secret
Rotate from the subscription's management surface. Accept both the old and the new secret during your cutover window, then stop accepting the old one.
Events available today
credential.issued
credential.revoked
issuance.completed
issuance.failed
verification.accepted
verification.completed
verification.rejected
issuer.delegation.created
issuer.delegation.submitted
issuer.delegation.approved
issuer.delegation.activated
issuer.delegation.suspended
issuer.delegation.revoked
issuer.delegation.reinstated
webhook.test
The broader catalogue in the DiligenceID programme — organisation, identity, integration and trust-status events — is not implemented. Do not subscribe to event types not listed above.