APIServices API

Webhooks

When a webhook is configured for your organization, ID.me 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 ID.me 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. ID.me will POST the transaction result to that URL when the transaction completes.

Example request body
1{
2  "phone": "8885551234",
3  "callback_url": "http://example.com/callback"
4}

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

If an error is received from your callback_url, ID.me 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
1{
2  "transaction_id": "c9298cc5-9917-4b88-850d-991df3864afe",
3  "verification_id": "e469c856-7f8e-4aba-8fb4-230bcfea7cf8",
4  "product": "license.verify",
5  "status": {
6    "code": 200,
7    "message": "Transaction successfully completed",
8    "created": "2023-04-04T17:15:52.171-04:00",
9    "updated": "2023-04-04T17:25:53.301-04:00"
10  }
11}