> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.id.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server.

# Webhooks

> Receive real-time transaction results via webhooks configured on your IDMe organization account.

When a webhook is configured for your organization, IDMe will POST the result of a verification transaction to your configured webhook URL. The body of the webhook POST request is the same format as the corresponding `GET /api/v2/:product/:transaction_id` response.

Webhook types:

* **Telecom Verification Result Webhook** — receives telecom transaction results
* **Document Verification Result Webhook** — receives document transaction results

Contact your IDMe account manager to configure webhooks for your organization.

## Using callback_url for per-request webhooks

In addition to organization-level webhooks, you can pass a `callback_url` parameter with any transaction request. IDMe will POST the transaction result to that URL when the transaction completes.

**`Example request body`**

```json Example request body
{
  "phone": "8885551234",
  "callback_url": "http://example.com/callback"
}
```

The `callback_url` will receive a POST with data in the same format as the `GET /api/v2/:product/:transaction_id` endpoint.

> **Warning**
>
> If an error is received from your `callback_url`, IDMe will retry the request 3 times before dropping the callback. You can always retrieve the result directly via the `GET /api/v2/:product/:transaction_id` endpoint.

## Testing webhooks with mock APIs

When testing with mock APIs, the `callback_url` must be an **unauthorized** (publicly accessible) endpoint — no authentication should be required to receive the POST.

## Example webhook payload

The following is an example of a Document License verification result delivered to a webhook or `callback_url`:

**`Example`**

```json Example
{
  "transaction_id": "c9298cc5-9917-4b88-850d-991df3864afe",
  "verification_id": "e469c856-7f8e-4aba-8fb4-230bcfea7cf8",
  "product": "license.verify",
  "status": {
    "code": 200,
    "message": "Transaction successfully completed",
    "created": "2023-04-04T17:15:52.171-04:00",
    "updated": "2023-04-04T17:25:53.301-04:00"
  }
}
```