Post webhooks

curl --request POST \ --url https://api.useanima.sh/v1/webhooks \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "url": "<string>", "events": [ "<string>" ], "description": "<string>", "active": true, "authConfig": { "type": "<unknown>" }, "rateLimitPerMinute": 50000, "maxAttempts": 5 } '

{ "id": "<string>", "orgId": "<string>", "url": "<string>", "events": [ "<string>" ], "active": true, "description": "<string>", "consecutiveFailures": 1, "disabledReason": "<string>", "disabledAt": "2023-11-07T05:31:56Z", "createdAt": "2023-11-07T05:31:56Z", "updatedAt": "2023-11-07T05:31:56Z", "authHeaderName": "<string>", "rateLimitPerMinute": 123, "maxAttempts": 123, "secret": "<string>" }

Authorizations

Authorization

string

header

required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Body

application/json

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

Event name or glob pattern. Examples: 'email.received', 'email.', 'call.ended', ''.

Required string length: 1 - 100

Pattern: ^[a-z0-9*]+(\.[a-z0-9*]+)*$

description

string

Optional human-readable label for this webhook

active

boolean

default:true

Whether the webhook is active and receiving events

authConfig

object

Auth the platform presents to your endpoint (in addition to the HMAC signature)

Option 1
Option 2
Option 3
Option 4

Show child attributes

rateLimitPerMinute

integer

Max deliveries per minute to this endpoint; omit for unlimited

Required range: 0 <= x <= 100000

maxAttempts

integer

Max delivery attempts before dead-lettering (default 3)

Required range: 1 <= x <= 10

Response

200 - application/json

Newly created webhook, including its one-time signing secret

string

required

Unique identifier for the webhook

Pattern: ^[0-9a-z]+$

orgId

string

required

Organization that owns this webhook

Pattern: ^[0-9a-z]+$

url

string<uri>

required

HTTPS endpoint URL receiving webhook payloads

events

string[]

required

Event types this webhook is subscribed to

Event name or glob pattern. Examples: 'email.received', 'email.', 'call.ended', ''.

Required string length: 1 - 100

Pattern: ^[a-z0-9*]+(\.[a-z0-9*]+)*$

active

boolean

required

Whether the webhook is currently active

description

string | null

required

Human-readable label for this webhook

consecutiveFailures

integer

required

Number of consecutive delivery failures across all events

Required range: x >= 0

disabledReason

string | null

required

Reason the webhook was auto-disabled, null if manually disabled or active

disabledAt

string<date-time> | null

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

enum<string>

required

Auth scheme the platform presents to your endpoint (never includes the secret)

Available options:

NONE,

BEARER,

BASIC,

CUSTOM_HEADER

authHeaderName

string | null

required

Header name for CUSTOM_HEADER auth; null for other schemes

rateLimitPerMinute

integer | null

required

Per-endpoint delivery rate cap in requests/minute; null = unlimited

maxAttempts

integer | null

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.