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.
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.
- Build and deploy your HTTPS webhook receiver before you create the Mailrith webhook subscription.
- Create the Mailrith webhook subscription with the receiver URL and a clear description.
- Copy and store the signing secret immediately because Mailrith returns the signing secret only when the subscription is created.
- Implement signature verification before your receiver trusts event payloads.
- Store received event IDs so duplicate deliveries do not create duplicate downstream work.
- Return a success response only after your receiver has accepted the event for processing.
- Regularly review webhook subscriptions in API Keys and Authorized Apps 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.
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.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.