> 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/reverse-sms/callbacks.md).

# Callbacks

{% hint style="info" %}
**Backend API** · Early Access
{% endhint %}

Reverse SMS emits a callback when a check reaches a terminal status (`COMPLETED`, `EXPIRED`, or `ERROR`). Because the completion trigger is the carrier receiving the user's SMS — not a backend PATCH — the callback is the primary signal that the verification has resolved.

## 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/reverse-sms-checks/{check_id}`.

The callback fires once per terminal status, with at-least-once delivery.

## Payload shape

The body mirrors the ReverseSMSCheck resource. 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 |
| `error_code`   | string   | Present when `status` is `ERROR` or `EXPIRED`      |

## HTTP headers

* `x-idlayr-callback: reverse_sms` — identifies the webhook source.
* Signed via JWKS. Validate the signature before trusting the payload.

## Delivery and retry

* First attempt is immediate when the check reaches a terminal status.
* On a non-2xx response, IDlayr retries with backoff (the same policy as Secure SNA — see [Callbacks for Secure SNA](/products/number-verification/secure-sna/callbacks.md#delivery-and-retry)).
* Treat `check_id` as the idempotency key.

## What your endpoint should do

1. **Verify the signature** before reading the body.
2. **Return 200 quickly.** Heavy work should be queued.
3. **Deduplicate by `check_id`.**
4. **Treat the callback as authoritative** — the user tapping Send in the SMS composer is not a verification result.

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/reverse-sms/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.