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

# Create webhook endpoint

`POST /v1/management/webhooks`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/v1/management/webhooks`
- Auth: HTTP bearer

Requires a workspace Management Token (mt-...), created at Dashboard > API > Management Tokens. Send Authorization: Bearer mt-.... Inference API keys (sk-...) and webhook signing secrets (whsec_...) are not accepted. Only the token workspace is accessible. The full whsec_ signing secret is returned only on creation or rotation. Store it securely; GET/list never return it. Rotation takes effect immediately for new deliveries; already in-flight deliveries can still use the previous secret. Up to 10 endpoints per workspace. Subscriptions cover future terminal async task events; existing tasks are not replayed.

## Request body

- CreateWebhookEndpointRequest
  - `url` string, uri, required: Public HTTPS receiver URL. Credentials, query strings, fragments, private or reserved network targets and redirects are rejected.
  - `events` string[], required: Supported event subscriptions; duplicates are removed.
  - `description` string

## Response `201`

Create webhook endpoint result

- CreatedWebhookEndpoint
  - `id` string, required
  - `object` 'webhook_endpoint', required
  - `url` string, required
  - `events` string[], required
  - `is_active` boolean, required
  - `description` string, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `last_delivered_at` string, date-time, nullable, required
  - `failure_count` integer, required
  - `secret` string, required

## Other responses

- `400`: Bad Request - Invalid input
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden
- `404`: Webhook not found in this workspace
- `409`: Endpoint quota reached or endpoint paused

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)