Webhooks
Webhook events
Reference for every Arrota webhook event: when it fires, its payload and how to handle it.
Updated
On this page
Every delivery body has the same envelope: event, data and signed_at. The tables below describe data for each event.
| Event | Fires when |
|---|---|
credential.issued | Your organisation issues a credential, from the dashboard, a bulk issuance or the API. |
credential.claimed | The recipient claims the credential into their Vault. |
credential.revoked | Your organisation revokes the credential. |
verification.requested | A verification request about one of your organisation's records is created. |
verification.decided | Your organisation finishes reviewing a verification request. |
credential.issued
Fires once per issued credential, including historical imports.
| Field | Type | Description |
|---|---|---|
document_id | string | The credential's ID, as returned by the Credentials API. |
credential_id | string or null | Your own reference number, if you set one. |
document_type | string | The document type, such as Certification. |
issued_on | date or null | The credential's issue date. |
{
"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"
}Handle it by recording document_id against the matching record in your system.
credential.claimed
Fires once, when the recipient first claims the credential.
| Field | Type | Description |
|---|---|---|
document_id | string | The claimed credential. |
claim_status | string | Pending Verification if the holder has not yet confirmed their personal email, or Verified if they have. |
{
"event": "credential.claimed",
"data": {
"document_id": "5b6f0c2a-1d3e-4f5a-9b7c-8d9e0f1a2b3c",
"claim_status": "Pending Verification"
},
"signed_at": "2026-09-19T08:41:02.530Z"
}Handle it by marking the credential as delivered. No event follows when the holder later confirms their email.
credential.revoked
| Field | Type | Description |
|---|---|---|
document_id | string | The revoked credential. |
revoked_at | timestamp | When it was revoked. |
reason | string or null | The reason recorded for the revocation. |
{
"event": "credential.revoked",
"data": {
"document_id": "5b6f0c2a-1d3e-4f5a-9b7c-8d9e0f1a2b3c",
"revoked_at": "2026-10-02T11:20:45.101882+00:00",
"reason": "Issued in error"
},
"signed_at": "2026-10-02T11:25:03.877Z"
}Handle it by marking the credential invalid in your system.
verification.requested
Fires when a request to confirm one of your organisation's records is created: when a holder asks you to confirm a record, or when a verifier submits a request about it. A verifier's request still needs the holder's authorisation, so it may never reach your review.
| Field | Type | Description |
|---|---|---|
request_id | string | The verification request. |
record_id | string | Your organisation's record it concerns. |
requested_at | timestamp | When the request was created. |
{
"event": "verification.requested",
"data": {
"request_id": "2c4e6a8b-0d1f-4a3c-b5e7-9a1c3e5b7d9f",
"record_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"requested_at": "2026-09-21T09:30:12.004511+00:00"
},
"signed_at": "2026-09-21T09:35:00.219Z"
}Handle it by alerting the team that answers requests. Requests are answered in the dashboard's Verification Inbox, not through the API.
verification.decided
Fires when a request that was waiting for your organisation's review is resolved. Requests your disclosure policy answers automatically do not wait for review and do not send this event.
| Field | Type | Description |
|---|---|---|
request_id | string | The verification request. |
record_id | string | The record it concerns. |
decision | string | Approved, Denied or Disputed. |
resolved_at | timestamp | When it was resolved. |
{
"event": "verification.decided",
"data": {
"request_id": "2c4e6a8b-0d1f-4a3c-b5e7-9a1c3e5b7d9f",
"record_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"decision": "Approved",
"resolved_at": "2026-09-22T16:04:51.918220+00:00"
},
"signed_at": "2026-09-22T16:05:02.640Z"
}Handle it by closing the matching item in your own queue.
General guidance
- Verify the signature before trusting any payload. See Verify signatures.
- Deliveries can arrive more than once and out of order. Use the IDs in
datato make processing idempotent. - Payloads are deliberately small and never include recipient names or email addresses. Use the Credentials API for more detail.