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 and retrieve calls return the whsec_ signing secret in the response body.

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 the 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.

Delivery guarantees

• At-least-once — every event is delivered at least once, but in rare cases (e.g. a network timeout after your server already processed the event) it may arrive more than once. Deduplicate on the svix-id header, which is unique per event and stable across retries.
• No ordering guarantee — events are sent as they occur, but network conditions and retries mean they can arrive out of order. For example, email.opened may arrive before email.delivered for the same email. If order matters, sort by the created_at timestamp in the payload after receipt.