Webhooks¶
Xref sends asynchronous notifications to a configured HTTPS endpoint when the overall status of a request changes.
Configuring a webhook¶
- Sign in to Xref as an organisation Owner.
- Navigate to Organisation Settings → Xref API.
- Enter an HTTPS endpoint URL and select Save. A webhook secret key will be displayed. See Verifying signatures.
Each organisation can have one outbound webhook configuration.
Delivery¶
When the overall request status changes, Xref sends a JSON payload to the configured HTTPS endpoint.
Sample webhook headers¶
Sample webhook body¶
RECEIVED → IN_PROGRESS
{
"event": "request.updated",
"event_id": "748528d7-b2a0-4f9b-bdca-4a2dc56b8e16",
"occurred_at": "2026-10-27T22:22:43.835982+00:00",
"request_id": "f979d290-2a38-4772-ab6b-a4cb6aeb5801",
"status": "IN_PROGRESS",
"previous_status": "RECEIVED",
"last_completed_at": null
}
IN_PROGRESS → PARTIAL
{
"event": "request.updated",
"event_id": "17e01b25-797d-491f-ba9a-d19b0a42d9f1",
"occurred_at": "2026-10-27T22:22:46.865872+00:00",
"request_id": "f979d290-2a38-4772-ab6b-a4cb6aeb5801",
"status": "PARTIAL",
"previous_status": "IN_PROGRESS",
"last_completed_at": null
}
PARTIAL → COMPLETED (first completion)
{
"event": "request.updated",
"event_id": "2e49a437-8d73-4c10-92d9-c31019c8104e",
"occurred_at": "2026-10-27T22:26:58.145657+00:00",
"request_id": "f979d290-2a38-4772-ab6b-a4cb6aeb5801",
"status": "COMPLETED",
"previous_status": "PARTIAL",
"last_completed_at": "2026-10-27T22:26:58.145657+00:00"
}
COMPLETED → PARTIAL (additional check required, e.g. replaced referee)
{
"event": "request.updated",
"event_id": "ed172f10-8792-4ee5-83ea-73f801a74ced",
"occurred_at": "2026-10-27T22:28:29.033551+00:00",
"request_id": "f979d290-2a38-4772-ab6b-a4cb6aeb5801",
"status": "PARTIAL",
"previous_status": "COMPLETED",
"last_completed_at": "2026-10-27T22:26:58.145657+00:00"
}
PARTIAL → COMPLETED (all additional checks completed)
{
"event": "request.updated",
"event_id": "4fd8ad7b-182f-4d5d-bf0a-11d92ff93a15",
"occurred_at": "2026-10-27T22:31:24.015353+00:00",
"request_id": "f979d290-2a38-4772-ab6b-a4cb6aeb5801",
"status": "COMPLETED",
"previous_status": "PARTIAL",
"last_completed_at": "2026-10-27T22:31:24.015353+00:00"
}
Headers¶
| Header | Description |
|---|---|
Content-Type |
Always application/json. |
X-Xref-Signature |
Lowercase hex digest of HMAC-SHA256(secret, raw_body). Verify before trusting the payload — see Verifying signatures. |
Body¶
| Field | Type | Description |
|---|---|---|
event |
string | Event name. v1 emits a single value: request.updated. |
event_id |
string (UUID) | Identifier for this status transition. A retry of the same transition repeats this value. A later transition for the same request has a new value. |
occurred_at |
string (ISO 8601) | When this status transition happened. |
request_id |
string (UUID) | Unique identifier for the request. Matches data.request_id returned by GET /v1/requests/{id}. |
status |
string | Updated overall request status: RECEIVED, IN_PROGRESS, PARTIAL, COMPLETED, ERROR, or CANCELLED. |
previous_status |
string | null | Status before this transition. null on the first transition. |
last_completed_at |
string (ISO 8601) | null | When the request last reached COMPLETED. null if it never has. Unchanged while the request is PARTIAL after it has left COMPLETED. Updated when the request reaches COMPLETED again. |
error_reason |
string | Present when status is ERROR. Provides additional diagnostic information about the failure. |
Verifying signatures¶
Webhook requests include an X-Xref-Signature header that can be used to verify that the request originated from Xref.
The signature is generated using HMAC-SHA256 with the webhook secret key and the raw request body.
Verify the signature against the raw request body before processing the payload. Use a constant-time comparison when comparing signatures.
Responding to webhooks¶
- Return a
2xxresponse within 10 seconds to acknowledge receipt. - A non-
2xxresponse, network failure, or timeout is treated as a delivery failure.
Retry policy¶
Failed webhook deliveries may be retried.
Webhook delivery should be treated as at least once, meaning the same event may be delivered more than once. Webhook handlers should therefore be idempotent and able to safely process duplicate events.
Identify a delivery by event_id. The same event_id is a retry of one transition. A later COMPLETED for the same request_id has a new event_id.
Event catalogue¶
v1 currently emits a single event:
| Event | When it fires |
|---|---|
request.updated |
Sent when the overall request status changes. The updated status is provided in status. |
A request.updated webhook is not sent when an individual check changes status without changing the overall request status.
For example, if a request is already IN_PROGRESS, another associated check moving from RECEIVED to IN_PROGRESS does not trigger a new request.updated event.
Webhooks signal status changes only. After a request.updated event, call
GET /v1/requests/{id} supplying an
X-Xref-User-Email that can read that request under
package access, such as an Owner, or the
user that created the request.
Security¶
- Webhook endpoints must use HTTPS.
- Store the webhook secret key securely alongside other API credentials.
- Verify the
X-Xref-Signatureheader before processing webhook payloads. - Generate and verify signatures using the raw request body.
- Make handlers idempotent — record processed
event_idvalues and ignore duplicates.