Create a webhook subscription

Creates a webhook subscription — the same result as adding one on the dashboard's webhooks page. Requires name, a publicly-reachable http(s) url, and at least one event code from the closed events enum. data_source scopes which connections feed the subscription: "all" (default) or a single connection id from GET /v1/integrations/{type}. The optional secret enables delivery signing (HMAC-SHA1 of the JSON data payload in the X-Request-Signature header) and is write-only — it can never be read back. Webhooks are a Business/Pro-plan feature (or the Webhooks add-on): requests from non-entitled plans → 403 forbidden. The first subscription automatically enables webhook delivery for your account. Delivery is best-effort (no ordering guarantee, may burst); after 5 failed delivery attempts a subscription is automatically deactivated (active: false). Honors Idempotency-Key (a retried POST with the same key replays the original 201).

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://api.mailfloss.com/v1/webhooks' \ --header 'Idempotency-Key;' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "string", "url": "string", "events": [ "status-undeliverable" ], "data_source": "string", "active": true, "secret": "string" }'

{ "id": "aBcDeFgHiJkLmNoPq", "name": "CRM sync — undeliverables", "url": "https://example.com/mailfloss/webhook", "events": [ "status-undeliverable", "job-finished" ], "data_source": "all", "active": true, "has_secret": true, "created_at": "2026-07-10T04:12:00.000Z", "updated_at": "2026-07-10T04:12:00.000Z" }

Create a webhook subscription

Request

Responses