Sotion

Webhooks

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 /webhooks

Create a webhook subscription

curl --request POST \
  --url 'https://api.sotion.so/api/v1/webhooks' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "value"
}'
{
  "data": {
    "id": "<uuid>",
    "name": "<string>",
    "url": "<url>",
    "events": [
      "member.created"
    ],
    "active": true,
    "secretPrefix": "<string>",
    "managedBy": "<string>",
    "createdAt": "<date-time>",
    "updatedAt": "<date-time>",
    "secret": "<string>"
  }
}

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

Authorizations

  • Authorization string required header

    Per-site API key (prefix: so_...). Each key is scoped to exactly one Sotion site — the site context is determined entirely by the key. No site ID is needed in any URL. Pass as: Authorization: Bearer so_...

Request Body

application/json
  • url string (uri) required

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

  • events[] string enum required arrayenum

    Event types to subscribe to. At least one required. Event type that can be subscribed to. See the Webhook Events reference for payload shapes. 9 allowed enum values.

  • name string

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

  • managedBy string

    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.

Response

application/json
  • Location string response header

    URL of the created webhook.

  • X-RateLimit-Limit integer response header

    Maximum requests allowed in the current window.

  • X-RateLimit-Remaining integer response header

    Requests remaining in the current window.

  • X-RateLimit-Reset integer response header

    Unix timestamp (seconds) when the rate limit window resets.

  • X-Request-Id string (uuid) response header

    Unique request identifier for support and debugging.

  • data allOf
    + Show Child Attributes
    • id string (uuid) allOf

      Unique identifier for the webhook subscription.

    • name string allOf

      Display name for the subscription. Auto-generated when not provided on create.

    • url string (uri) allOf

      HTTPS delivery URL. Sotion POSTs signed event envelopes here.

    • events[] string enum allOfarrayenum

      Event types this subscription receives. Event type that can be subscribed to. See the Webhook Events reference for payload shapes. 9 allowed enum values.

    • active boolean allOf

      Whether the subscription is currently delivering events.

    • secretPrefix string allOf

      First 10 characters of the signing secret, used to identify which secret an integration holds. The full secret is only returned on create.

    • managedBy string allOfnullable

      External system that owns this subscription (e.g. 'zapier'). Null when user-managed via the dashboard.

    • createdAt string (date-time) allOfnullable

      When the subscription was created.

    • updatedAt string (date-time) allOfnullable

      When the subscription was last modified.

    • secret string allOf

      Full HMAC-SHA256 signing secret (prefix 'whsec_'). Returned ONCE on create — persist it to verify X-Webhook-Signature on incoming deliveries.