---
title: "Create webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create webhook

`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`

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

## Request body

- WebhookCreateRequest
  - `url` string, uri, required: HTTPS URL to receive webhook notifications
  - `events` string[], required: Events to subscribe to

## Response `200`

Webhook created

- ApiResponse
  - `success` boolean: Whether the request was successful
  - `code` string: Response code ("0" for success)
  - `message` string: Human-readable message
  - `data` object: Response data (varies by endpoint)

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - invalid or missing API key

---

[API](https://skmtc.dev/billionverify/apis/billionverify-api.md) · [All operations](https://skmtc.dev/billionverify/apis/billionverify-api/llms.txt) · [OpenAPI document](https://skmtc.dev/billionverify/apis/billionverify-api/revisions/00762347dc27?raw)