Create a webhook subscription

Creates a new webhook subscription. Sotion will POST a signed JSON envelope to url whenever any of the given events fire.

The response includes the full signing secret — this is the ONLY time it is returned. Persist it to verify incoming X-Webhook-Signature: sha256= headers. The signature is an HMAC-SHA256 of the raw request body using this secret.

url must be HTTPS. Each site is limited to 10 active webhook subscriptions.

Optionally set managedBy (e.g. 'zapier') to mark the subscription as owned by an external system — the Sotion dashboard will show it as read-only so users don't accidentally edit it.

POST /api/v1/webhooks

Bearer token

curl 'https://api.sotion.so/api/v1/webhooks' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com",
  "events": [
    "member.created"
  ],
  "name": "example",
  "managedBy": "example"
}'

{
  "data": {
    "id": "123e4567-e89b-42d3-a456-426614174000",
    "name": "example",
    "url": "https://example.com",
    "events": [
      "member.created"
    ],
    "active": true,
    "secretPrefix": "example",
    "managedBy": "example",
    "createdAt": "2026-01-01T12:00:00Z",
    "updatedAt": "2026-01-01T12:00:00Z",
    "secret": "example"
  }
}

Webhook created. The full signing secret is returned in the body — save it.

Body

· CreateWebhookRequest

required application/json

url string · uri required

HTTPS delivery URL. Must start with https://. Sotion POSTs signed event envelopes here.

events array of WebhookEvent · min items: 1 required

Event types to subscribe to. At least one required.

values

member.created
member.updated
member.auth
member.deleted
access-group.created
access-group.updated

name string · min length: 1· max length: 100

Optional display name. Auto-generated from events/managedBy if omitted.

managedBy string · min length: 1· max length: 50

Optional marker for integrations to identify their own subscriptions (e.g. 'zapier'). Subscriptions with managedBy set are shown as read-only in the Sotion dashboard.

Body

Responses