Managing webhooks

Webhooks push email events to your own server in near-real time, so you do not have to poll. When an email is delivered, opened, clicked, bounces, or is complained about, MailBlastr sends an HTTP POST with a JSON body to the endpoint(s) you have configured.

Each delivery is signed so you can verify it really came from MailBlastr — see Verify webhook requests.

Configuring an endpoint

1. 1
   Add an endpoint

   In the dashboard, add a webhook with the HTTPS URL that should receive events. The URL must be publicly reachable over HTTPS and resolve to a public IP (private/loopback addresses are rejected).

2. 2
   Choose events

   Select which events the endpoint should receive. Events you do not subscribe to are never delivered. See Event types for the full list.

3. 3
   Save the signing secret

   A whsec_ signing secret is generated for the endpoint and shown once. Store it securely — you will use it to verify every incoming request.

4. 4
   Verify and go live

   Use the dashboard Test button to send a sample delivery, confirm your endpoint returns a 2xx, then start handling live events.

Webhooks can also be managed programmatically via the API — see Create webhook, List webhooks, and the retrieve/update/delete endpoints. The create call returns the whsec_ signing secret in the response body; retrieve and list never do. If you lose it, POST /webhooks/:id/rotate issues a new one and invalidates the old.

The payload

Each delivery is a JSON body in the envelope { "type", "created_at", "data" }, where data holds the resource-specific fields for that event. See Event types for the envelope and a sample, and the per-event pages for each data shape.

The signing secret

Each endpoint has its own signing secret. MailBlastr uses it to compute an HMAC-SHA256 signature over "<X-Mailblastr-Timestamp>.<raw request body>" and sends that in the X-Mailblastr-Signature header. Keep the secret server-side — anyone with it can forge events. The secret is stored encrypted at rest.

Delivery, timeouts, and retries

Each delivery is a single POST with a 10-second timeout. A delivery is considered successful only on a 2xx response.

• On failure, MailBlastr retries — up to 5 attempts total (the initial attempt plus 4 retries).
• Retries use an increasing backoff of roughly 1, 5, 30, then 120 minutes.
• The attempt number is included in each request as the X-Mailblastr-Attempt header (starting at 1), so you can detect retries.
• An endpoint that fails 50 consecutive deliveries is automatically disabled. Re-enable it from the dashboard once your endpoint is healthy.

Duplicates, ordering, and exhausted retries

• Duplicates are possible — a timeout can occur after your server has processed a request. Deduplicate on the svix-id header, which stays stable across retries of a delivery. Persist accepted events before acknowledging them.
• Retries are bounded — a delivery can remain unsuccessful after the attempt limit, or while an endpoint is disabled. Monitor failures and reconcile important email states through the API; successful receipt of every event is not guaranteed.
• No ordering guarantee — network conditions and retries can change arrival order. Keep event history and apply event-aware state updates so a late event does not incorrectly reverse a later state. The payload timestamp helps investigation, but sorting received timestamps alone cannot recover a missing event or resolve every state transition.