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

# Create Webhook

`POST /v1/webhooks`

Create a new webhook endpoint. Returns the webhook configuration including a secret for signature verification. The secret is only shown once. Requires API key with webhook:write.

## Request body

- CreateWebhookRequest
  - `url` string, uri, required — The webhook endpoint URL (must be HTTPS)
  - `events` string[], required — Array of event types to subscribe to (e.g., email.generation.completed)
  - `description` string — Optional description for the webhook
  - `customHeaders` object — Optional custom headers to include in webhook requests

## Response `201`

Webhook created

- ApiResponseWebhookCreated
  - `success` boolean, required
  - `data` object, nullable
    - `id` string — Webhook ID
    - `url` string, uri — The webhook endpoint URL
    - `events` string[] — Subscribed event types
    - `active` boolean — Whether the webhook is active
    - `secretConfigured` boolean — Whether a signing secret is configured. The secret value itself is returned only once, in the create response.
    - `description` string — Optional description
    - `successCount` integer — Number of successful deliveries
    - `failureCount` integer — Number of failed deliveries
    - `lastTriggeredAt` string, date-time — Last trigger timestamp
    - `createdAt` string, date-time — Creation timestamp
    - `updatedAt` string, date-time — Last update timestamp
    - `secret` string — Webhook secret for signature verification (only shown once upon creation)
  - `error` string, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized

---

[API](https://skmtc.net/migma/apis/migma-ai-api-v1.md) · [All operations](https://skmtc.net/migma/apis/migma-ai-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/migma/migma-ai-api-v1/revisions/3f3dba69574b/schema)