---
title: "POST /webhooks"
method: POST
path: "/webhooks"
---

# POST /webhooks

`POST /webhooks`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/webhooks`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Request body

- object: Request body for creating a new webhook subscription
  - `url` string, uri, required: HTTPS endpoint URL that will receive webhook POST payloads
  - `events` string[], required: List of event types this webhook subscribes to
  - `description` string: Optional human-readable label for this webhook
  - `active` boolean: Whether the webhook is active and receiving events
  - `authConfig` union: Auth the platform presents to your endpoint (in addition to the HMAC signature)
    - object: No customer auth header (the HMAC signature is still sent)
      - `type` 'none', required
    - object
      - `type` 'bearer', required
      - `token` string, required: Sent as `Authorization: Bearer <token>`
    - object: Sent as `Authorization: Basic <base64(username:password)>`
      - `type` 'basic', required
      - `username` string, required
      - `password` string, required
    - object: Sent as a custom header `<headerName>: <value>`
      - `type` 'custom_header', required
      - `headerName` string, required
      - `value` string, required
  - `rateLimitPerMinute` integer: Max deliveries per minute to this endpoint; omit for unlimited
  - `maxAttempts` integer: Max delivery attempts before dead-lettering (default 3)

## Response `200`

OK

- object: Newly created webhook, including its one-time signing secret
  - `id` string, required: Unique identifier for the webhook
  - `orgId` string, required: Organization that owns this webhook
  - `url` string, uri, required: HTTPS endpoint URL receiving webhook payloads
  - `events` string[], required: Event types this webhook is subscribed to
  - `active` boolean, required: Whether the webhook is currently active
  - `description` string, nullable, required: Human-readable label for this webhook
  - `consecutiveFailures` integer, required: Number of consecutive delivery failures across all events
  - `disabledReason` string, nullable, required: Reason the webhook was auto-disabled, null if manually disabled or active
  - `disabledAt` string, date-time, nullable, required: ISO 8601 timestamp when the webhook was auto-disabled
  - `createdAt` string, date-time, required: ISO 8601 timestamp when the webhook was created
  - `updatedAt` string, date-time, required: ISO 8601 timestamp when the webhook was last modified
  - `authType` 'NONE' | 'BEARER' | 'BASIC' | 'CUSTOM_HEADER', required: Auth scheme the platform presents to your endpoint (never includes the secret)
  - `authHeaderName` string, nullable, required: Header name for CUSTOM_HEADER auth; null for other schemes
  - `rateLimitPerMinute` integer, nullable, required: Per-endpoint delivery rate cap in requests/minute; null = unlimited
  - `maxAttempts` integer, nullable, required: Per-webhook max delivery attempts; null = platform default (3)
  - `secret` string, required: The signing secret, returned ONLY at creation time. Store it now — read endpoints (get/list) never return it again. Use it to verify the X-Anima-Signature header on every delivery. If lost, rotate via POST /webhooks/{id}/rotate-secret.

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)