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

# Create Webhook

`POST /webhooks`

Registers a new webhook URL to receive notifications for verification events. Users can optionally specify which events to subscribe to using the 'events' array. Supports `verification.completed` (when verification finishes) and `verification.historical` (when historical employment data becomes available) events. If events are not specified, the webhook subscribes to all available events by default.

## Request body

- WebhookCreate
  - `description` string — Description of the webhook.
  - `endpoint_url` string, uri, required — The URL to send the webhook notifications to.
  - `events` string[] — Array of event types to subscribe to. If not provided, defaults to all available events.
  - `authentication` union — Authentication configuration for the webhook.
    - object
      - `type` 'jwt', required
      - `secret` string, required — Secret used to generate the JWT.
      - `expiration_seconds` integer, required — Expiration time of the JWT in seconds.
    - object
      - `type` 'custom_headers', required
      - `headers` object, required — Custom headers to include in the webhook request.
    - object
      - `type` 'token_endpoint', required
      - `url` string, uri, required — URL to fetch the token from.
      - `method` 'GET' | 'POST', required
      - `request_headers` object — Headers to send with the token request.
      - `request_body` object — Body to send with the token request.
      - `response_key` string, required — Key to extract the token from the response.

## Response `201`

Webhook created successfully.

- Webhook
  - `id` string, uuid — Unique identifier for the webhook.
  - `company_id` string, uuid — Company identifier owning the webhook.
  - `description` string — Description of the webhook.
  - `endpoint_url` string, uri — URL to send the webhook notifications to.
  - `secret_key` string — A secret key used to verify the signature in the X-Signature header of the webhook, ensuring that the webhook request originates from the Income Bureau.
  - `is_active` boolean — Whether the webhook is active.
  - `events` string[] — Array of event types this webhook is subscribed to.
  - `created_at` string, date-time — Timestamp when the webhook was created.
  - `updated_at` string, date-time — Timestamp when the webhook was last updated.
  - `authentication` union — Authentication configuration for the webhook.
    - object
      - `type` 'jwt', required
      - `secret` string, required
      - `expiration_seconds` integer, required
    - object
      - `type` 'custom_headers', required
      - `headers` object, required
    - object
      - `type` 'token_endpoint', required
      - `url` string, uri, required
      - `method` 'GET' | 'POST', required
      - `request_headers` object
      - `request_body` object
      - `response_key` string, required

## Other responses

- `400` — Bad Request - Invalid events array.
- `401` — Unauthorized - Invalid or missing API key.

---

[API](https://skmtc.net/burodeingresos/apis/bur-de-ingresos-api.md) · [All operations](https://skmtc.net/burodeingresos/apis/bur-de-ingresos-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/burodeingresos/bur-de-ingresos-api/versions/59e48cdbdd84/schema)