Rotate the signing secret

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

Authorizations

Authorization

string

header

required

Sendmux API key. Use a root API key for Management API routes, or a mailbox credential for Mailbox API routes. Obtain keys from the dashboard under API Keys.

Headers

Idempotency-Key

string

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

Maximum string length: 255

Example:

"webhooks-rotate-20260424-001"

Path Parameters

public_id

string

required

Webhook public ID

Response

Subscription with new signing secret

enum<boolean>

required

Available options:

true

meta

object

required

Hide child attributes

meta.request_id

string

required

Example:

"req_clxxxxxxxxxxxxxxxxxxxxxxxxx"

data

object

required

Hide child attributes

data.id

string

required

Webhook public ID

Example:

"whk_clxxxxxxxxxxxxxxxxxxxxxxxxx"

data.name

string | null

required

Optional human-friendly label used in dashboard list/detail pages. May be null for subscriptions created without a name.

Example:

"Acme inbound forwarder"

data.url

string<uri>

required

HTTPS endpoint that receives signed event POSTs.

Example:

"https://hooks.acme.com/sendmux"

data.event_types

enum<string>[]

required

Event types this subscription receives.

Event types a webhook may subscribe to. sendmux.test is accepted so you can verify end-to-end delivery via POST /webhooks/{id}/test.

Available options:

message.delivered,

message.bounced,

message.complained,

message.rejected,

message.delivery_delayed,

message.received,

message.received.spam,

sendmux.test

Example:

["message.bounced", "message.received"]

data.filters

object

required

Optional delivery scope. Empty mailbox_ids means all team mailboxes.

Hide child attributes

data.filters.mailbox_ids

string[]

required

Mailbox public IDs to receive events for. Empty means all mailboxes in the team.

Example:

["mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx"]

data.enabled

boolean

required

When false, no events are delivered to this subscription.

Example:

true

data.failing

boolean

required

True when the 24-hour retry window has been exhausted for this subscription. Reset by updating the subscription (e.g. fixing the URL) and re-enabling.

Example:

false

data.created_at

string

required

ISO 8601 creation timestamp

Example:

"2026-04-23T09:12:00Z"

data.updated_at

string

required

ISO 8601 last-modified timestamp

Example:

"2026-04-23T09:12:00Z"

data.secret

string

required

Signing secret used to verify the HMAC-SHA256 signature on every event POST. This is the ONLY response containing the raw secret — store it securely; it cannot be retrieved later. Use POST /webhooks/{id}/rotate-secret to issue a new one.

Example:

"whsec_a9f3c2…"