Webhooks

Create webhook

Create a new webhook to receive notifications for file verification events.

Available events:

  • file.completed - File verification job completed successfully
  • file.failed - File verification job failed

The webhook secret is returned only on creation. Store it securely for signature verification.

Security requirements:

  • Webhook URLs must use HTTPS
  • X-Webhook-Signature is sha256=<hex>
  • Verify the signature over {X-Webhook-Timestamp}.{raw_body}
  • Reject old timestamps to reduce replay risk
post/v1/webhooks

Request

  • Base URL: https://api.billionverify.com
  • URL: https://api.billionverify.com/v1/webhooks
  • Auth: API key in header BV-API-KEY

Request body

urlstring uri required

HTTPS URL to receive webhook notifications

eventsstring[] required

Events to subscribe to

Example request

{
  "url": "https://your-app.com/webhooks/billionverify",
  "events": [
    "file.completed",
    "file.failed"
  ]
}

Response

Webhook created

successboolean

Whether the request was successful

codestring

Response code ("0" for success)

messagestring

Human-readable message

dataobject

Response data (varies by endpoint)

Changes

No recorded changes to this operation across all 1 revision of this API.