> For the complete documentation index, see [llms.txt](https://docs.qiro.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qiro.fi/developer-section/qiro-instant-settlement/webhooks.md).

# Webhooks

Qiro sends signed webhooks for partner-relevant lifecycle changes. Webhooks are notifications; status endpoints remain authoritative.

## Delivery model

* Delivery is at least once.
* Retries keep the same `event_id`.
* The receiver must deduplicate by `event_id`.
* Use `resource_version` to order updates for the same resource.
* Do not assume global ordering across resources.
* Return `2xx` only after durable receipt.

## Signature verification

Qiro signs the exact raw request body with a shared webhook secret and timestamp.

Receiver requirements:

1. Capture the raw request body bytes before JSON parsing.
2. Read the timestamp and signature headers defined in the OpenAPI specification.
3. Reject stale timestamps according to the configured tolerance.
4. Recompute the HMAC over `timestamp.rawBody`.
5. Compare the expected and received signatures using a timing-safe comparison.
6. Parse JSON only after signature verification succeeds.

Do not verify a re-serialized JSON object. Whitespace and field order matter because the signature covers the raw body.

## Reconciliation

If a webhook is missed, duplicated, or delayed, call the relevant status endpoint:

* `GET /v1/drawdowns/{drawdown_id}`
* `GET /v1/repayments/{repayment_id}`
* `GET /v1/facility-closures/{closure_id}`
* `GET /v1/facility-activations/{activation_id}`

Webhook payloads include the resource type, resource ID, facility ID, status, correlation ID, resource version, and blockchain evidence when relevant.

Current webhook resources are drawdowns, repayments, facility closures, and facility activations. Recovery webhooks are a future workflow and are not emitted by the current API.
