> For the complete documentation index, see [llms.txt](https://docs.idlayr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.idlayr.com/products/number-verification/secure-sna/callbacks.md).

# Callbacks

{% hint style="info" %}
**Device API** · NV 1.0 · GA
{% endhint %}

Secure SNA emits a callback when a check reaches a terminal status (`COMPLETED`, `EXPIRED`, or `ERROR`). Callbacks let your backend act on the final result without polling.

## When callbacks are sent

A callback is sent if you supplied a `callback_url` on the create request. If you didn't, you can still learn the final state by polling `GET /v1/number-verification/secure-sna-checks/{check_id}`.

The callback fires once per terminal status, with at-least-once delivery (see Retry below).

## Payload shape

The body mirrors the SecureSNACheck resource, omitting the transient fields (`url`, `ttl`) that have no meaning on a terminal callback. Fields:

| Field          | Type     | Notes                                              |
| -------------- | -------- | -------------------------------------------------- |
| `check_id`     | UUID     | Use as the idempotency key                         |
| `status`       | string   | `COMPLETED`, `EXPIRED`, or `ERROR`                 |
| `match`        | boolean  | Only present when `status` is `COMPLETED`          |
| `created_at`   | ISO 8601 | When the check was created                         |
| `updated_at`   | ISO 8601 | When the check reached the terminal state          |
| `reference_id` | string   | Echoes whatever you supplied on the create request |
| `network_id`   | string   | Present when `status` is `COMPLETED`               |
| `error_code`   | string   | Present when `status` is `ERROR` or `EXPIRED`      |

## HTTP headers

* `x-idlayr-callback: secure_sna` — identifies the webhook source. Use this to route incoming POSTs on a shared endpoint.
* The callback is signed via a JWKS keypair. Validate the signature before trusting the payload — see Callbacks for the verification flow.

## Delivery and retry

* First attempt is immediate when the check reaches a terminal status.
* On a non-2xx response (or no response), IDlayr retries up to 6 more times with backoff intervals of **10s, 20s, 30s, 40s, 50s, 60s** — \~3.5 minutes elapsed total before IDlayr gives up.
* Ordering across different checks is not guaranteed.
* Treat `check_id` as the idempotency key. The same payload may arrive more than once.

## What your endpoint should do

1. **Verify the signature** before reading the body. An unsigned or wrongly-signed POST is not from IDlayr.
2. **Return 200 quickly.** Heavy work (DB writes, downstream calls) should be queued; the callback handler should ack within a few hundred ms to avoid retries.
3. **Deduplicate by `check_id`.** A repeat callback for the same check should be a no-op.
4. **Don't trust device-side results without backend confirmation.** A callback is the authoritative signal; a device returning a code is not.

For the full signing model — algorithm, header layout, JWKS endpoint, verification steps, and key rotation — see [Signed HTTP messages](/get-started/signed-http-messages.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.idlayr.com/products/number-verification/secure-sna/callbacks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.