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

# Callbacks

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

Discovery emits a callback when a check reaches a terminal status (`COMPLETED`, `EXPIRED`, or `ERROR`). The callback carries the discovered MSISDN on success — your backend treats this as the authoritative signal.

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

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

## Payload shape

The body mirrors the DiscoveryCheck resource. Fields:

| Field          | Type         | Notes                                                                                                                                 |
| -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `check_id`     | UUID         | Use as the idempotency key                                                                                                            |
| `status`       | string       | `COMPLETED`, `EXPIRED`, or `ERROR`                                                                                                    |
| `phone_number` | E.164 string | The discovered MSISDN. 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`. See [Error codes](/products/number-verification/discovery/error-codes.md) for the enum |

## HTTP headers

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

## Delivery and retry

Same policy as Secure SNA — see [Callbacks for Secure SNA](/products/number-verification/secure-sna/callbacks.md#delivery-and-retry).

## What your endpoint should do

1. **Verify the signature** before reading the body.
2. **Return 200 quickly.**
3. **Deduplicate by `check_id`.**
4. **Treat the callback as authoritative.** Discovery's success path returns personally identifying data — store it only after verifying the callback is genuine.
5. **Route the terminal-state cases.** A `status: COMPLETED` carries the discovered MSISDN. `EXPIRED` and `ERROR` mean the discovery didn't complete (MNO not supported, no cellular data, TTL elapsed, MNO-side failure); route these to your fallback verification path.

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