# Webhook Subscriptions API > Webhook subscriptions let external systems receive Mailrith events for syncs, dashboards, fulfillment, and audit trails. This guide explains when to use webhooks, how to manage subscriptions, why you must store the signing secret immediately, and how receivers should verify and deduplicate deliveries. - Human page: https://mailrith.com/developers/webhook-subscriptions - Markdown page: https://mailrith.com/developers/webhook-subscriptions.md - Category: API Resources - Reading time: 7 min read - Last updated: 2026-06-13 - Related keywords: Webhook Subscriptions API, Webhook Subscriptions API developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Subscribe External Systems to Mailrith Events, Endpoint Overview, Verify Webhook Delivery, Privacy And Consent In Webhooks, Broadcasts API, Subscribers API, API Reference ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What this guide covers Create signed event subscriptions for CRMs, dashboards, audits, and workflow systems. ## Subscribe External Systems to Mailrith Events Webhook subscriptions let an external system receive event notifications from Mailrith. Use webhook subscriptions for CRM updates, internal dashboards, fulfillment systems, audit pipelines, reporting, and workflow tools that need to react when an event happens. A webhook uses a push model. Instead of polling Mailrith repeatedly, your system exposes an HTTPS endpoint, and Mailrith sends events to that endpoint. Use a public HTTPS receiver URL. Mailrith does not send webhook events to localhost, private network, link-local, or reserved destinations. Keep webhook endpoints stable and observable. If your receiver URL or receiver behavior changes, update the Mailrith subscription before you rely on the event stream. 1. Build and deploy your HTTPS webhook receiver before you create the Mailrith webhook subscription. 2. Create the Mailrith webhook subscription with the receiver URL and a clear description. 3. Copy and store the signing secret immediately because Mailrith returns the signing secret only when the subscription is created. 4. Implement signature verification before your receiver trusts event payloads. 5. Store received event IDs so duplicate deliveries do not create duplicate downstream work. 6. Return a success response only after your receiver has accepted the event for processing. 7. Regularly review webhook subscriptions in [API Keys and Authorized Apps](https://mailrith.com/docs/api-keys-and-authorized-apps.md) or in your internal integration inventory. Confirm each subscription has the correct endpoint, owner, and purpose. - Use webhooks when another system needs to react soon after a Mailrith event. - Use polling when the external system only needs occasional reporting and does not need event-by-event updates. - Store received event IDs so your system can ignore duplicate deliveries safely. - Return a successful response only after your receiver has accepted the event for processing. - Keep webhook receiver logs private because event payloads may contain workspace or subscriber data. ## Endpoint Overview Use webhook subscription endpoints to list, create, inspect, update, and delete event subscriptions for the authenticated workspace. `POST /v1/webhook-subscriptions` creates a subscription and returns the signing secret once. Store the signing secret immediately because your receiver needs the secret to verify that future event deliveries came from Mailrith. Before you update a subscription, confirm that the new endpoint is deployed and can receive events successfully. Before you delete a subscription, confirm that the downstream system no longer depends on those events. Related OpenAPI operation groups: - Webhook Subscriptions **Create a Webhook Subscription** ```bash curl -X POST https://api.mailrith.com/v1/webhook-subscriptions \ -H "Authorization: Bearer mrk_example_secret_key" \ -H "Idempotency-Key: crm-webhook-v1" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/mailrith/events", "description": "Send Mailrith events to the CRM sync service", "enabled": true }' ``` ## Verify Webhook Delivery Webhook deliveries are signed. Verify the signature before you trust the event payload. Signature verification protects your endpoint from accepting fake Mailrith events. Mailrith includes delivery metadata in headers such as `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Use the signing secret returned at subscription creation to verify the signature according to the webhook verification logic used by your receiver. After verification, process events idempotently. Network retries can deliver the same event more than once, and your receiver must not create duplicate downstream work. - Store the signing secret in a secret manager, not in source control. - Reject events with missing or invalid signatures. - Reject very old timestamps if your receiver enforces a replay window. - Use the event ID or delivery ID to deduplicate downstream processing. - Return a non-2xx response only when you want Mailrith to consider the delivery failed. ## Privacy And Consent In Webhooks Webhook payloads can include Subscriber or workspace event data. Treat the receiver as a downstream system that may need its own access controls, retention rules, and subscriber request review. Choose event patterns narrowly. A CRM sync may need Subscriber created and updated events, while an audit pipeline may need form and landing-page submissions. Do not subscribe a destination to every event family just because it is convenient. Today, public webhooks include Subscriber created, updated, and status-changed events, plus form, landing-page, broadcast, and automation events. They do not include separate public events for consent withdrawal, privacy request completion, objection, restriction, or erasure. When a webhook changes a Subscriber's status or profile, apply that state in the receiving system before it sends more marketing email, tracks engagement, or syncs the Subscriber into another tool. For access, deletion, restriction, objection, or withdrawal requests, keep a separate downstream review process until Mailrith exposes dedicated public webhook events. - Subscribe to the smallest useful set of event patterns. - Keep webhook destinations, owners, and retention notes in your integration inventory. - Do not log secrets, signing secrets, or full payload bodies into shared logging systems. - Process Subscriber status and profile changes from current webhook events before downstream systems send or track the Subscriber again. - Include webhook destinations in data-subject request and account-shutdown reviews. > For the boundary between public API Subscriber fields and Mailrith-hosted consent workflows, see [Consent And Privacy API Boundaries](https://mailrith.com/developers/consent-and-lawful-basis.md). ## Related Guides - [Broadcasts API](https://mailrith.com/developers/broadcasts.md): The broadcasts resource is the public campaign control plane for one-off messages. This guide explains draft management, test sends, live-send safety, and why integrations and agents should treat send actions as high-impact operations. - [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the main way integrations write Subscriber data in `v1`. This guide explains when to list subscribers, when to upsert subscribers, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests. - [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.