---
title: "Create a webhook endpoint"
method: POST
path: "/api/v3/webhook_endpoints/"
tags: ["Webhooks"]
---

# Create a webhook endpoint

`POST /api/v3/webhook_endpoints/`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/webhook_endpoints/`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `dts_session_id`
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/webhook_endpoints/post.ts> (a function with typed inputs; its response is checked against the schema)

Register a new webhook endpoint and subscribe it to one or more event types. The endpoint is created
in `unverified` status and a fresh `secret` is returned in the response. Use the `verify` action to
activate the endpoint.

> **Important:** `event_types` must contain identifiers returned by `GET /api/v3/webhook_event_types/`
> (e.g. `load_completed`, `transformation_completed`). Unknown event names are accepted by the
> request but no deliveries will be sent for them — always source the names from the event types
> endpoint rather than hard-coding them.

## Request body

- WebhookEndpointCreateRequest
  - `url` string, uri, required: HTTPS URL of the receiver that will accept event deliveries.
  - `event_types` string[]: Event types this endpoint will subscribe to. See `GET /api/v3/webhook_event_types/` for the list of available event names. Duplicates are deduplicated server-side. May be empty.

## Response `201`

Webhook endpoint created

- WebhookEndpointDetail: Full webhook endpoint representation, including the signing secret and the list of subscriptions. The `secret` is used to compute the `X-Improvado-Signature` header (HMAC-SHA256) on every event delivery and as the verification token during the verify flow. Treat it as sensitive and store it securely.
  - `id` integer
  - `url` string, uri
  - `secret` string: 64-character hex signing secret
  - `status` 'unverified' | 'active'
  - `consecutive_failures` integer
  - `subscriptions` WebhookSubscription[]
    - `id` integer: Subscription ID
    - `event_type_name` string: Name of the event type this subscription receives
    - `is_active` boolean: Whether the subscription is active
    - `created_at` string, date-time: When the subscription was created
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Validation error
- `401`: Authentication credentials were not provided.
- `403`: Embedded API is not enabled for this agency, or workspace header is missing.

---

[API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)