---
title: "Verify a webhook endpoint"
method: POST
path: "/api/v3/webhook_endpoints/{id}/verify/"
tags: ["Webhooks"]
---

# Verify a webhook endpoint

`POST /api/v3/webhook_endpoints/{id}/verify/`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/webhook_endpoints/{id}/verify/`
- 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/:id/verify/post.ts> (a function with typed inputs; its response is checked against the schema)

Trigger ownership verification of the endpoint URL.

Improvado sends a `GET` request to the endpoint URL with the headers:

- `X-Improvado-Verify-Token` — the endpoint's signing secret
- `X-Improvado-Challenge` — a one-time random token

The receiver must respond with HTTP 200 and the value of `X-Improvado-Challenge` as the response body.
On success, the endpoint transitions to `active`. On failure (non-200 status, mismatching body, or
connection error), the endpoint remains `unverified` and a 400 is returned.

## Path parameters

- `id` integer, required

## Response `200`

Endpoint verified successfully (status is now `active`)

- 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`: Verification failed (unreachable URL, non-200 response, or challenge mismatch)
- `401`: Authentication credentials were not provided.
- `404`: Webhook endpoint not found

---

[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)