Sign in
Webhooks

Create a webhook subscription

Changed on

Creates a new webhook subscription and returns the signing secret ONCE in the response body. Store it securely — it cannot be retrieved later. Use POST /webhooks/{id}/rotate-secret to issue a new one.

Supply an Idempotency-Key header (any unique string, max 255 chars) to safely retry on network errors. Replays with the same key return the original response; replays with a different body return 409 idempotency_conflict.

post/webhooks

Request

  • Base URL: https://app.sendmux.ai/api/v1
  • URL: https://app.sendmux.ai/api/v1/webhooks
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://app.sendmux.ai/oauth/authorize, token URL https://app.sendmux.ai/oauth/token, scopes: webhook.create)

Headers

Idempotency-Keystring

Client-chosen unique key to safely retry the request. Cached for 24h per (team, endpoint, key). Different body with same key returns 409 idempotency_conflict.

Example:webhooks-create-20260424-001

Request body

enabledboolean

Defaults to true.

event_typesstring[] required

At least one event type must be provided.

namestring

Optional human-friendly label (max 255 chars). Surfaced in dashboard list/detail views.

urlstring uri required

HTTPS endpoint that will receive event POSTs. Must be https:// — plain HTTP is rejected.

Example request

{
  "enabled": true,
  "event_types": [
    "message.bounced",
    "message.received"
  ],
  "filters": {
    "mailbox_ids": [
      "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"
    ]
  },
  "name": "Acme inbound forwarder",
  "url": "https://hooks.acme.com/sendmux"
}

Response

Subscription created, including the signing secret. The response carries a Location header pointing at the canonical GET URL for the new subscription.

oktrue required

Example response

{
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "data": {
    "created_at": "2026-04-23T09:12:00Z",
    "enabled": true,
    "event_types": [
      "message.bounced",
      "message.received"
    ],
    "filters": {
      "mailbox_ids": [
        "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    },
    "id": "whk_clxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "Acme inbound forwarder",
    "secret": "whsec_a9f3c2…",
    "updated_at": "2026-04-23T09:12:00Z",
    "url": "https://hooks.acme.com/sendmux"
  }
}

Changes

  • b901839a0d8bRevision changes
    • breaking

      the / response's property type changed from no type to object for status

    • info

      removed subschema #2 from the / response property allOf list for the response status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

  • 7807ce923952Revision changes
    • info

      the endpoint scheme security oauth2 was added to the API