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.

Each organisation can have one outbound webhook configuration in v1.

Delivery

When the overall request status changes, Xref sends an HTTPS POST request to the configured webhook endpoint.

Request

POST /your/webhook HTTP/1.1
Host: webhooks.yourcompany.com
Content-Type: application/json
X-Xref-Signature: 7c9b1e6d6b4cdcdb2a1f3a91…  (hex hmac-sha256 of the raw body)

{
  "event": "request.updated",
  "request_id": "9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a",
  "status": "COMPLETED"
}

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.
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.
error_reason	string	Present when status is ERROR. Provides additional diagnostic information about the failure.

The body is the exact byte sequence over which the signature is computed. Verify the signature against the raw bytes of the request body before parsing it as JSON.

Example — ERROR payload

{
  "event": "request.updated",
  "request_id": "9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a",
  "status": "ERROR",
  "error_reason": "api.xref.io 400: package not active for organisation"
}

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 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.

The combination of request_id and status can be used to identify previously processed status updates.

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.

Security

• Webhook endpoints must use HTTPS.
• Store the webhook secret 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 (request_id, status) pairs and ignore duplicates.