Webhooks
Webhooks overview
Receive signed HTTPS events when credentials are issued, claimed or revoked and when verification requests arrive or are decided.
Updated
On this page
Webhooks tell your systems when something happens to your organisation's credentials and records, so you do not have to poll.
How it works
- You register an HTTPS endpoint and choose the events it receives.
- Arrota gives you a signing secret, once.
- When an event happens, Arrota queues it in the same transaction as the change it describes, then sends a signed
POSTto your endpoint, usually within a few minutes. - Your endpoint verifies the signature, responds with a
2xxstatus, and processes the event.
Webhooks describe your organisation's own credentials and records. Verifiers track their own verification requests through the Verification API, not webhooks.
Register an endpoint
In your issuer dashboard, open Settings, then API & Webhooks, and select Add a webhook. Enter the endpoint URL and choose one or more events. Copy the signing secret from the confirmation; it is not shown again.
Your endpoint must:
- use
https, on a publicly reachable host name (up to 500 characters), - respond within 10 seconds,
- answer directly: redirects are not followed.
Only a Super Admin or Admin can manage webhooks, and your plan must include them. The step-by-step guide is Configure a webhook endpoint.
What a delivery looks like
POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Arrota-Event: credential.issued
X-Arrota-Signature: sha256=3c1f0e...
X-Arrota-Timestamp: 2026-09-18T14:02:14.112Z
X-Arrota-Delivery: 6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d{
"event": "credential.issued",
"data": {
"document_id": "5b6f0c2a-1d3e-4f5a-9b7c-8d9e0f1a2b3c",
"credential_id": "CERT-2026-0042",
"document_type": "Certification",
"issued_on": "2026-09-18"
},
"signed_at": "2026-09-18T14:02:14.112Z"
}| Header | Meaning |
|---|---|
X-Arrota-Event | The event name, also in the body as event. |
X-Arrota-Signature | sha256= followed by the hex HMAC-SHA256 of the raw body. See Verify signatures. |
X-Arrota-Timestamp | When the delivery was signed. Matches signed_at in the body. |
X-Arrota-Delivery | A unique ID for this delivery. |
Manage endpoints
From API & Webhooks you can Pause and Resume an endpoint, Rotate secret, Remove it, and see Recent deliveries with a Retry action. A paused endpoint receives no new events. See Retries and replay.
Webhook payloads never include recipient names or email addresses. For how Arrota protects data in transit and at rest, see Security.