Skip to main content
A webhook is an endpoint on your server that mailkube calls with an HTTP POST each time something you care about happens. That can be an email event (a delivery, a bounce, an open, or a click) or a lifecycle change to one of your sending domains or webhook endpoints. You subscribe a URL to a set of events and mailkube pushes them to you as they occur. Webhooks are managed in the dashboard by organization owners, admins, and members. The billing role has no access.

How a delivery reaches you

Three properties of that flow decide how you build the receiver.
  • Each event type reaches one endpoint per domain. Subscriptions cannot overlap. Moving an event to a second endpoint takes it off the first, with no redelivery of anything already in flight.
  • The POST is a request you answer within 10 seconds. Acknowledge first and queue the work. A handler that does its own database writes inline is the usual cause of a retry storm.
  • The response status is the only signal mailkube reads. It does not parse your body and it does not follow a redirect.
Your endpoint’s first-attempt acceptance rate is measured over a rolling window. An endpoint that keeps failing on the first try is disabled automatically; see Endpoint health and automatic disabling.

Adding an endpoint

Before mailkube saves an endpoint, it verifies that you control the URL you entered. Your server answers a one-time challenge before you submit. The listener has to be running and publicly reachable before you submit the form. The challenge is sent during creation, not after it.
1

Answer the verification challenge

When you add an endpoint, mailkube sends a single GET to your URL:
Your server must reply 200 OK with a body equal to the token, within 5 seconds. There is no shared verify token; echoing the challenge is the proof.
If the challenge isn’t echoed (wrong body, a non-200 status, a redirect, a TLS error, or a timeout), the endpoint is not created.
2

Choose what to send

email.bounced fires only on a permanent failure (the address is dead). A temporary problem, a deferral or a message that ran out of retries, arrives as email.delivery_delayed instead, so a later attempt may still deliver.
email.suppressed fires when a recipient is filtered from a send. Two things suppress an address: it previously hard-bounced (scoped to your sending domain’s apex: a bounce on mail.acme.com also suppresses news.acme.com), or it unsubscribed from an opt-out topic this send was attributed to. The send is accepted and counts against your quota, but the message is dropped before delivery. It produces no email.delivered and no email.bounced. data.suppression.recipients lists the suppressed addresses; remove them from your own lists to stop paying for sends that can never deliver.
When the endpoint is saved, mailkube shows its signing secret once, a 64-character hex string. Copy it and store it somewhere safe; it is never shown again. If you lose it, roll the secret to generate a new one.

Verifying signatures

Every delivery is signed with your endpoint’s signing secret so you can confirm it really came from mailkube. Each POST carries three headers: The signature is computed over the delivery id, the timestamp, and the exact raw body, joined with dots. This is the wire contract. Reach for it if you are on a language with no mailkube SDK:
Everywhere else, don’t implement it. Every SDK ships the check: hand it the raw bytes and the request headers, and it validates the signature in constant time, rejects a delivery whose X-Webhook-Ts has aged past a 300-second window, and returns a typed event.
The entry point in each SDK: On a supported framework, the integration package carries the whole receiver: it verifies the raw body, answers the delivery, and hands your code a typed event through the framework’s own dispatch mechanism. An event type your installed version does not model still reaches your handler with its payload intact. A new platform event never breaks a running receiver.

Receiving them from the terminal

The CLI runs a verified receiver on your machine, which covers local development and CI without a deployed endpoint:
listen answers the registration challenge itself, so start it before you add the endpoint in the dashboard. Its --filter, --exit-after and --exit-timeout flags turn the listener into an assertion a CI job can make about a send.
Verify over the raw request body. A re-serialized JSON won’t match: round-tripping reorders keys and normalizes whitespace. Reject a delivery whose signature or timestamp doesn’t check out. Because X-Webhook-Ts is fresh per attempt, a legitimately delayed retry still passes, while a replayed delivery is rejected once its timestamp ages past the tolerance.
For local development. Start from webhook-inspector, a boilerplate receiver that answers the verification challenge and prints the events it receives. It verifies signatures with the official mailkube Python SDK (verify_signature / parse_event). It opens a Cloudflare Tunnel (cloudflared) to expose your local server at a public https:// URL you can add to mailkube. It’s meant for development and testing; it is not production-grade.

Signing, for your tests

Production code verifies; it never signs. But to exercise your handler without waiting on a real delivery, each SDK exposes the signing half too, sign in Python and Node, Webhooks.sign in Ruby, PHP and Java, and mailkube.Sign in Go:
sign computes the HMAC exactly as verify checks it, so a fixture built this way can’t drift from the verifier the way a hand-rolled one eventually does. It takes the timestamp you give it and doesn’t judge its freshness. Pass a stale one to confirm your handler rejects a replay.

Email events

Every email event shares a common envelope of a type, a created_at, and a data block whose message context (email_id, from, to, subject, domain, and any tags you attached to the send) identifies the message. Each event adds one nested object with its specifics. All timestamps are ISO-8601 UTC: the envelope’s created_at spells the offset as +00:00, while the timestamps inside data use the Z form; both carry fractional seconds when the instant has them. (The email.suppressed payload is shown above; its data follows the same shape with a suppression block.) The email_id is the same UUID across every event for one message. It threads the whole lifecycle, from email.scheduled (if it was scheduled) through email.sent (accepted for delivery) to email.delivered, email.bounced, or email.failed. A receiving server can accept a message and report a delivery failure later. Your endpoint then gets an email.bounced, or an email.delivery_delayed for a temporary failure, after the email.delivered for the same email_id.

email.scheduled

The send was accepted for later transmission, and a scheduled email was created. Fires at schedule time, once quota is charged and the body is rendered. scheduled.batch_id is null when the send wasn’t grouped into a batch.

email.sent

The message was accepted and spooled by the mail transfer agent, the handoff moment before any delivery outcome. It precedes any email.delivered or email.bounced for the same email_id, and carries no SMTP response, so sent is a recipient plus a timestamp.
email.sent fires for every transmitted message, immediate and scheduled alike. Subscribing to it means one extra event per send, on top of whatever delivery outcome follows. It is a handoff signal, not a delivery confirmation; use email.delivered for the outcome.

email.delivered

The message was accepted by the recipient’s mail server.

email.bounced

A permanent failure. The address is dead, and code and reason carry the receiving server’s response.

email.delivery_delayed

A temporary problem, a deferral or a message that ran out of retries. A later attempt may still deliver. Same shape as a bounce, under a delay key.

email.opened

The recipient opened the message. This example shows the default: the sending domain has not enabled either connection-data setting, so the open block carries only a timestamp. See Recipient connection data.

email.clicked

The recipient clicked a tracked link. link is the clicked URL. This example shows a domain that has enabled both connection-data settings; see Recipient connection data.

Recipient connection data

ipAddress, country and userAgent are the only keys in any payload whose presence depends on your configuration. Two per-domain settings control them, both off by default: Both are on the domain’s settings page in the dashboard, below the click and open tracking toggles. Three things to know before you turn them on:
  • A key you have not enabled is absent, not null and not "". Your handler can tell “not recorded” from “recorded blank”. Each SDK surfaces that absence in its own idiom, an optional type or a zero value.
  • country can be absent even when ipAddress is present. It is resolved at the edge and is not available on every path, so treat it as optional too.
  • Recording this data can require your recipient’s consent, depending on where they are. You are the controller of that decision and responsible for having any permission the law requires; mailkube records the fields on your instruction and uses them for nothing of its own.
Turning a setting off takes effect on the very next open or click. It does not remove data already recorded, which ages out on your plan’s log retention window.

email.failed

A scheduled email the platform had already accepted was terminally dropped at send time. Without this event, an email you scheduled 30 days out could be dropped silently; subscribe to it to catch that. It shares the email_id of the earlier email.scheduled, and is distinct from email.suppressed (which fires at the normal send-path gate): email.failed marks a send the platform had already accepted for later. failed.reason is a stable code, never a raw transport string, one of:

Lifecycle events

Beyond per-message email events, two events tell you when your resources change state. Your integration never polls for them.

domain.status

Fires whenever one of your sending domains changes status or onboarding_state, as it progresses through onboarding, is suspended (on_hold) for reputation or as part of an apex-wide suspension, has that suspension lifted, or is deleted. The payload carries the new state plus a previous block so you can diff the transition:

webhook.status

Fires whenever one of your webhook endpoints changes state: you disable or re-enable it, mailkube auto-disables it for low quality, or it is deleted. disabled_reason distinguishes a manual (user) disable from an automatic (low_quality) one.
Because each event goes to one endpoint per domain, a webhook.status event about an endpoint is delivered to whichever endpoint subscribes to webhook.status, and never to an endpoint that is being disabled or deleted (only active endpoints receive deliveries). Point webhook.status at a separate, always-on endpoint if you want to observe these changes reliably.

Delivery and retries

A delivery is an HTTPS POST with the signed payload. Your server has 10 seconds to answer with a success status; hand slow work to a queue and return early. Redirects are never followed, on the verification challenge or on deliveries. The endpoint URL must answer directly. A failed attempt is retried with exponential backoff. The first retry waits two minutes, each following wait doubles, and the wait stops growing at 48 hours. mailkube makes 15 attempts in total, then abandons the delivery. X-Webhook-Id stays stable across every one of them, so deduplicate on it. A payload over 64 KB cannot be delivered and is dropped rather than retried. Anything outside 2xx is a failed attempt, a 3xx included: an endpoint that redirects spends its attempt budget on redirects. Connection failures, TLS errors and timeouts count the same way.

Editing an endpoint

Open an endpoint in the dashboard to change it:
  • Endpoint URL. Moving to a new URL re-runs the verification challenge above.
  • Events. Adjust which events you receive at any time.
  • Active. Turn an endpoint off to pause delivery without losing it, and back on to resume. An endpoint that keeps failing may also be disabled automatically; see Endpoint health and automatic disabling.
The domain is fixed for the life of an endpoint. To send a domain’s events to a different one, delete the endpoint and add a new one.

Endpoint health and automatic disabling

Each endpoint carries a first-attempt acceptance rate: how often your server returns a success status on the first delivery attempt, measured over a rolling window. A failed delivery is still retried with backoff; the rate measures how healthy the endpoint is overall. An endpoint whose rate stays low, once it has carried enough recent traffic to judge, is disabled automatically so it stops spending your retry budget on a target that isn’t accepting events. When that happens:
  • The endpoint appears in your list as disabled with a “Low quality” reason, distinct from one you turned off yourself.
  • Anyone subscribed to the Webhook health alerts email topic for your organization is notified, with the endpoint URL and the acceptance rate that triggered it.
An endpoint records why it is disabled (by you, or by mailkube for low quality) and, for an automatic disable, its quality score: the first-attempt acceptance rate (0 to 1) captured at the moment it was disabled. A healthy endpoint carries no score.
To bring it back, fix the receiving endpoint, then re-enable it the same way you’d resume a paused one (toggle Active back on). Its rate is measured again from a clean slate. Only a fresh failure streak could disable it again.

Rotating the signing secret

If your signing secret is lost or exposed, you can roll it from the endpoint’s menu in the dashboard. Rolling generates a fresh secret and shows it once, exactly like creation.
The previous secret stops working immediately. Any receiver that verifies the signature must be updated to the new secret, or its deliveries will fail signature checks. Rolling cannot be undone.
The endpoint, its URL, and its event subscriptions are unchanged; only the secret changes, so there is no new verification challenge. Rolling is rate-limited per endpoint.
  • Domains. An endpoint subscribes to events from one active domain.
  • Quickstart. Send the emails whose events you’ll receive.
  • Receiving webhooks with the CLI. Run a verified receiver locally, replay a capture, and assert delivery in CI.
  • SDKs. Every SDK verifies a delivery, and the four framework packages carry the whole receiver.