Skip to content

Webhooks

Xref sends asynchronous notifications to a configured HTTPS endpoint when the overall status of a request changes.

Configuring a webhook

  1. Sign in to Xref as an organisation Owner.
  2. Navigate to Organisation Settings → Xref API.
  3. 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

Content-Type: application/json
X-Xref-Signature: 7c9b1e6d6b4cdcdb2a1f3a91…

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 2xx response within 10 seconds to acknowledge receipt.
  • A non-2xx response, 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-Signature header before processing webhook payloads.
  • Generate and verify signatures using the raw request body.
  • Make handlers idempotent — record processed event_id values and ignore duplicates.