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 the signing secret must be stored immediately, and how receivers should verify and deduplicate deliveries.
7 min read
Subscribe External Systems to Mailrith Events
Webhook subscriptions let an external system receive event notifications from Mailrith. They are useful for CRM updates, internal dashboards, fulfillment systems, audit pipelines, reporting, and workflow tools that need to react when something happens.
A webhook is a push model. Instead of polling Mailrith repeatedly, your system exposes an HTTPS endpoint and Mailrith sends events to it.
Keep webhook endpoints stable and observable. If your receiver changes, update the Mailrith subscription before depending on the event stream.
- Build and deploy your HTTPS webhook receiver first.
- Create the Mailrith webhook subscription with the receiver URL and a clear description.
- Copy and store the signing secret immediately because Mailrith returns it only when the subscription is created.
- Implement signature verification before trusting 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.
- Review webhook subscriptions regularly in API Keys and Authorized Apps or your internal integration inventory.
- 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 duplicates 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 that secret immediately because it is needed to verify that future event deliveries came from Mailrith.
When updating a subscription, confirm the new endpoint is already deployed and able to receive events. When deleting a subscription, confirm 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 trusting the event payload. This 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 cause the same event to arrive 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.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.
Related Guides
Create campaign drafts, send tests, and protect live broadcast sends with deliberate approval.
List and upsert subscribers with practical guidance for identity, tags, fields, syncs, and imports.
Browse generated endpoint details and download the exact OpenAPI contract for tooling.