← Back to docs

Real-time Webhooks

Get instant delivery notifications via signed webhooks

Menu

How delivery works

EuroMail POSTs a JSON payload to your endpoint URL for every event your webhook is subscribed to. Each attempt:

  • Uses POST with Content-Type: application/json.
  • Times out after 10 seconds.
  • Carries these headers, exactly as cased below:
HeaderValue
X-Euromail-Signaturet=<unix_timestamp>,v1=<hex hmac-sha256> — see Signature verification
X-Euromail-EventThe event type, e.g. sent
X-Euromail-AttemptThe attempt number, starting at 1

Any 2xx response counts as delivered. A 5xx response or a timeout is treated as transient and retried (see Retries). Any other response — 4xx, or anything else that isn't 2xx/5xx — is treated as permanent and is not retried, since it means your endpoint understood the request and rejected it.

EuroMail does not currently publish a stable, dedicated outbound IP range for webhook delivery — unlike SMTP sending, which does use a small set of fixed, warmed IPs (see IP Warmup) — so IP allowlisting isn't a supported way to authenticate requests. Verify the signature instead.

Signature verification

Every payload is signed with HMAC-SHA256 using your webhook's signing secret (shown once at creation, and viewable again from the webhook's detail page in the dashboard). The signature travels in X-Euromail-Signature as t=<unix_timestamp>,v1=<hex_signature> — the same shape Stripe uses.

To verify:

  1. Split the header on , to get t (a Unix timestamp) and v1 (a hex string).
  2. Reject the request if abs(now - t) exceeds a tolerance window. 5 minutes (300 seconds) is the default in the PHP SDK's verifier and the value the snippets below use. This bounds how long a captured request stays replayable.
  3. Recompute the signature as hex(hmac_sha256(secret, "{t}.{raw_request_body}")) — the raw bytes of the body exactly as received, not a re-serialized copy.
  4. Compare your computed signature to v1 using a constant-time comparison (hmac.compare_digest, crypto.timingSafeEqual, hash_equals, and so on). A plain == leaks timing information an attacker can use to forge a signature byte by byte.

The header always carries exactly one t= and one v1=. Rotating the secret from the dashboard generates a new one and signs every later delivery with it. A delivery your endpoint rejects with a 4xx is not retried, so update your verifier right after rotating, or accept both secrets for a short window.

Node.js

const crypto = require("crypto");

function verifyWebhookSignature(payload, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=").map((s) => s.trim()))
  );
  const timestamp = parts.t;
  const signature = parts.v1;
  if (!timestamp || !signature) return false;

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    return false;
  }

  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hmac
import hashlib
import time


def verify_webhook_signature(payload: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp = parts.get("t")
    signature = parts.get("v1")
    if not timestamp or not signature:
        return False

    if abs(time.time() - int(timestamp)) > tolerance:
        return False

    signed_payload = f"{timestamp}.{payload.decode()}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Go

func verifyWebhookSignature(payload []byte, header, secret string, tolerance time.Duration) bool {
	var timestamp, signature string
	for _, part := range strings.Split(header, ",") {
		kv := strings.SplitN(strings.TrimSpace(part), "=", 2)
		if len(kv) != 2 {
			continue
		}
		switch kv[0] {
		case "t":
			timestamp = kv[1]
		case "v1":
			signature = kv[1]
		}
	}
	if timestamp == "" || signature == "" {
		return false
	}

	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return false
	}
	if age := time.Since(time.Unix(ts, 0)); age > tolerance || -age > tolerance {
		return false
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp))
	mac.Write([]byte("."))
	mac.Write(payload)
	expected := hex.EncodeToString(mac.Sum(nil))

	return subtle.ConstantTimeCompare([]byte(expected), []byte(signature)) == 1
}

Rust

use hmac::{Hmac, Mac};
use sha2::Sha256;
use subtle::ConstantTimeEq;

type HmacSha256 = Hmac<Sha256>;

fn verify_webhook_signature(payload: &[u8], header: &str, secret: &str, tolerance_secs: i64) -> bool {
    let mut timestamp = None;
    let mut signature = None;
    for part in header.split(',') {
        let mut kv = part.trim().splitn(2, '=');
        if let (Some(k), Some(v)) = (kv.next(), kv.next()) {
            match k {
                "t" => timestamp = Some(v),
                "v1" => signature = Some(v),
                _ => {}
            }
        }
    }
    let (Some(timestamp), Some(signature)) = (timestamp, signature) else {
        return false;
    };
    let Ok(ts) = timestamp.parse::<i64>() else {
        return false;
    };
    let now = chrono::Utc::now().timestamp();
    if (now - ts).abs() > tolerance_secs {
        return false;
    }

    let mut mac = HmacSha256::new_from_slice(secret.as_bytes()).expect("valid HMAC key");
    mac.update(timestamp.as_bytes());
    mac.update(b".");
    mac.update(payload);
    let expected = hex::encode(mac.finalize().into_bytes());

    let (Ok(sig_bytes), Ok(expected_bytes)) = (hex::decode(signature), hex::decode(&expected)) else {
        return false;
    };
    expected_bytes.ct_eq(&sig_bytes).into()
}

PHP

The PHP SDK ships this verifier — EuroMail\Webhooks\WebhookSignature::verify() — so most integrators never need to hand-roll it:

use EuroMail\Webhooks\WebhookSignature;

$payload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_EUROMAIL_SIGNATURE'] ?? '';
$secret = getenv('EUROMAIL_WEBHOOK_SECRET');

if (!WebhookSignature::verify($payload, $signatureHeader, $secret)) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);

Without the SDK, the equivalent is:

function verify_webhook_signature(string $payload, string $header, string $secret, int $tolerance = 300): bool {
    $timestamp = null;
    $signature = null;
    foreach (explode(',', $header) as $part) {
        [$key, $value] = array_map('trim', explode('=', $part, 2));
        if ($key === 't') { $timestamp = $value; }
        if ($key === 'v1') { $signature = $value; }
    }
    if ($timestamp === null || $signature === null) {
        return false;
    }
    if (abs(time() - (int) $timestamp) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
    return hash_equals($expected, $signature);
}

Check your implementation

Run your verifier against this fixed test vector — a real HMAC-SHA256 computed with openssl, not a made-up value — and confirm it produces the same v1:

secret:    whsec_test_secret_do_not_use
timestamp: 1735689600
body:      {"event":"sent","email_id":"018f2c3a-7b1e-7c3e-8b1a-2f6e9d4c5a01","account_id":"018f2c3a-7b1e-7c3e-8b1a-2f6e9d4c5a02","timestamp":"2025-01-01T00:00:00Z"}
expected v1: fe8eb85890a5a24fdc2e7be82ca402c124a44abaa4aa1f289e298274e3d5c261

Reproduce it yourself with:

echo -n '1735689600.{"event":"sent","email_id":"018f2c3a-7b1e-7c3e-8b1a-2f6e9d4c5a01","account_id":"018f2c3a-7b1e-7c3e-8b1a-2f6e9d4c5a02","timestamp":"2025-01-01T00:00:00Z"}' \
  | openssl dgst -sha256 -hmac whsec_test_secret_do_not_use

If your function returns a different hex string, the signed input is wrong before you touch timestamps or comparisons — check that you're hashing "{t}.{raw_body}" with the raw request body bytes, not a JSON-decoded and re-encoded copy (re-encoding can reorder keys or change whitespace, which changes the hash).

Event catalogue

Every event carries event, account_id and a timestamp (RFC 3339), plus the fields listed under it below. IDs are UUIDs, not the em_.../acc_... prefixed style used elsewhere in these docs.

Every email event (sent, deferred, bounced, failed, opened, clicked and complained) also carries the metadata and tags you attached when you sent the email, exactly as you sent them. metadata is null and tags is [] when the send had none, so you can read both keys without checking they exist.

Payloads are additive: new fields may appear over time (an authentication object on inbound events, for example). Parse defensively and ignore unknown fields.

This list is complete. You can subscribe to every event on it, and we send every one of them.

sent

Fired when the recipient's mail server accepts the message, answering our DATA with a 2xx reply. That is as far as any sender can see, so there is no separate "delivered" event. If a bounce report comes in later, you get a bounced event then.

smtp_response is the receiving server's reply and ip_address is the IP we sent from.

{
  "event": "sent",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2026-09-03T14:32:01Z",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Your order has shipped",
  "domain": "yourdomain.com",
  "smtp_response": "250 2.0.0 OK",
  "ip_address": "198.51.100.34",
  "metadata": { "order_id": "A1" },
  "tags": ["receipt"]
}

sent covers the email's primary (To) recipient. A CC or BCC copy that is accepted does not fire it.

delivered is accepted as an alias for sent. It used to be listed as an event of its own, but we never sent it, since it marks the same moment as sent. Webhooks that listed it now listen to sent, and a webhook created or updated with delivered is stored with sent instead.

deferred

Fired each time a send is held back and will be tried again: the recipient's domain is being throttled, a provider asked us to back off, or the SMTP attempt failed temporarily. It has the same fields as sent, plus reason and next_retry_at. smtp_response and ip_address stay null until a receiving server has accepted the message.

{
  "event": "deferred",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2026-09-03T14:32:01Z",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Your order has shipped",
  "domain": "yourdomain.com",
  "smtp_response": null,
  "ip_address": null,
  "reason": "domain_throttled: gmail.com throttle_pct=40%",
  "next_retry_at": "2026-09-03T14:47:01Z"
}

bounced

Fired when the message bounced, which happens in one of three ways:

  • While we were sending, the receiving server refused the recipient address. The payload has the same fields as sent, and reason holds the refusal.
  • A temporary failure kept coming back until the retries ran out. Same fields, with reason holding the last failure. The email's status is failed in this case, since the address itself was never refused.
  • A bounce report (DSN) arrived after the message was sent. This payload carries the same fields as sent, plus bounce_type (hard or soft), bounce_category, remote_mta and diagnostic_code.
{
  "event": "bounced",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2026-09-03T14:32:01Z",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Your order has shipped",
  "domain": "yourdomain.com",
  "smtp_response": null,
  "ip_address": "198.51.100.34",
  "reason": "550 5.1.1 The email account that you tried to reach does not exist"
}

failed

Fired when the message will not be delivered for a reason other than the recipient address. The receiving server refused it on policy grounds, a problem on our side (DNS, connection, signing) stopped it, or every sending IP was blocked for that provider until the hold ran out. The email's status is failed and nothing more is attempted. It has the same fields as bounced above, with reason saying what went wrong. If a message was stuck mid-send and we cannot tell whether it went out, reason says so, and the event still carries the send's fields, metadata and tags.

For a CC or BCC copy, deferred, bounced, failed, opened and clicked fire for that copy on its own, with to set to the copy's recipient and recipient_type set to cc or bcc.

opened

Fired the first time a recipient's mail client loads the open-tracking pixel (deduplicated to once per 5 minutes; known scanner/proxy user agents, including Gmail's image proxy, are filtered out so a prefetch doesn't count as an open).

{
  "event": "opened",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2026-09-03T14:35:12Z"
}

clicked

Fired when a recipient follows a tracked link (deduplicated per link, per 30 seconds). Carries one extra field:

{
  "event": "clicked",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2026-09-03T14:36:40Z",
  "link_url": "https://yourdomain.com/orders/12345"
}

complained

Sent when an ISP feedback loop (FBL/ARF) tells us a recipient marked the message as spam. We only send it when we can tie the report to an email you sent, using either the feedback address on that email or its Message-ID. If we can't match a report, we archive it internally and it never triggers a webhook or a suppression.

You get this event at most once per recipient of an email. We ignore repeat reports.

to_address is the email's recipient, the same as on every other event. complainer is the person who complained, and we add that address to your suppression list. The complainer can be a CC or BCC recipient. Each recipient's copy carries its own feedback address, so the report tells us who sent it. If an email had several recipients and we can't trace a report about it to one of them, we keep the report for review and don't send this event. Every recipient who complains counts toward the complaint rate. original_message_id is the email's Message-ID exactly as the API returns it.

{
  "event": "complained",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "to_address": "[email protected]",
  "complainer": "[email protected]",
  "feedback_type": "abuse",
  "original_message_id": "<[email protected]>",
  "timestamp": "2026-09-03T15:02:11Z"
}

account.auto_paused

Sent when sending on your account is paused. We pause an account automatically when its bounce or complaint rate crosses our abuse thresholds, or when our content check flags a second, different message as possible phishing while an earlier one is still waiting for review. Our team can also pause an account after a review. The account owner gets an email explaining the reason, and this event arrives within about 30 seconds of the pause. source tells you what paused the account: reputation, scam_classifier, registration_burst or admin. See Automated Abuse Protection.

{
  "event": "account.auto_paused",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "source": "reputation",
  "reason": "bounce_rate=12.4% over last 500 sends (threshold 10%)",
  "timestamp": "2026-09-03T16:00:00Z"
}

email.inbound

Fired when a message arrives on a domain with inbound routing configured and the matching route has a webhook URL attached (see Inbound Email).

{
  "event": "email.inbound",
  "inbound_email_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "domain": "yourdomain.com",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Question about my order",
  "text_body": "...",
  "html_body": "...",
  "attachments": [],
  "message_id": "<[email protected]>",
  "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },
  "sender": { "hostname": "mail-ed1-f45.google.com", "hostname_status": "confirmed", "service": "Google", "helo": "mail-ed1-f45.google.com", "country": "IE", "country_name": "Ireland" },
  "source_ip": "203.0.113.10",
  "timestamp": "2026-09-03T16:05:00Z"
}

mailbox.message.received

Fired when a message arrives in an agent mailbox.

{
  "event": "mailbox.message.received",
  "mailbox_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "from": "[email protected]",
    "reply_to": null,
    "subject": "Question about my order",
    "text_body": "...",
    "text_body_stripped": "...",
    "html_body": "...",
    "attachments": [],
    "message_id": "<[email protected]>",
    "in_reply_to": null,
    "references": null,
    "thread_id": "770e8400-e29b-41d4-a716-446655440002",
    "classification": { "label": "support_request", "confidence": 0.94 },
    "received_at": "2026-09-03T16:05:00Z"
  },
  "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },
  "sender": { "hostname": "mail-ed1-f45.google.com", "hostname_status": "confirmed", "service": "Google", "helo": "mail-ed1-f45.google.com", "country": "IE", "country_name": "Ireland" },
  "source_ip": "203.0.113.10",
  "timestamp": "2026-09-03T16:05:00Z"
}

text_body_stripped is only present when quoted reply text was detected and removed; classification is only present when the mailbox has automatic classification enabled.

insights.generated

Fired when a new deliverability insights report is ready for your account, whether it was scheduled or you asked for it. summary is the report's one-paragraph summary. Fetch the full report by insight_id.

{
  "event": "insights.generated",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "insight_id": "880e8400-e29b-41d4-a716-446655440003",
  "summary": "Bounce rate fell to 0.8% this week; Outlook deferrals are still above normal.",
  "timestamp": "2026-09-03T17:00:00Z"
}

test

Sent only when you press "Send test" in the dashboard or call POST /v1/webhooks/{id}/test. You don't subscribe to it, and every webhook can receive it. See Dashboard testing.

{
  "event": "test",
  "webhook_id": "990e8400-e29b-41d4-a716-446655440004",
  "account_id": "660e8400-e29b-41d4-a716-446655440001",
  "timestamp": "2026-09-03T17:05:00Z",
  "data": { "message": "This is a test webhook event from EuroMail." }
}

Idempotency

Webhook deliveries are not deduplicated on your end automatically — a retry after a timeout, or (rarely) a duplicate delivery, can arrive twice. Use the event's identifying field — email_id for send-lifecycle events, inbound_email_id for email.inbound, message.id for mailbox.message.received, or insight_id for insights.generated — together with event as your dedup key.

Automatic retry with backoff

If your endpoint returns a 5xx response or the request times out, EuroMail retries with exponential backoff: 15 minutes, 30 minutes, 1 hour, then 2 hours between attempts (base 15 minutes, doubling each time, plus a few seconds of random jitter to avoid a thundering herd). A 4xx response, or any other non-5xx failure, is treated as permanent and is not retried at all.

After 5 total attempts for a given event, delivery is given up on and the event is logged as undeliverable in the dashboard's delivery history for that webhook — there is currently no automatic replay of an individual failed event from the dashboard.

Separately, a webhook that racks up 10 consecutive delivery failures (across all events, not just one) is automatically deactivated — no further attempts are made until you edit the webhook (even without changing anything) to reactivate it, which also resets the failure count. A webhook you paused yourself, rather than one the system paused, stays paused until you turn it back on the same way.

Configuration

Webhook URLs can be configured per account. Use the API or dashboard to set up endpoints:

curl -X POST https://api.euromail.dev/v1/webhooks \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/euromail",
    "events": ["sent", "deferred", "bounced", "failed", "opened", "clicked",
               "complained", "email.inbound", "mailbox.message.received",
               "account.auto_paused", "insights.generated"]
  }'

The URL must use HTTPS. The response includes the signing secret — store it, it's shown in full only at creation (and can be revealed again, or rotated, from the webhook's detail page in the dashboard).

To see, change or remove webhooks:

# All webhooks (paged with page and per_page)
curl "https://api.euromail.dev/v1/webhooks?page=1&per_page=25" \
  -H "Authorization: Bearer em_live_..."

# One webhook
curl https://api.euromail.dev/v1/webhooks/{id} \
  -H "Authorization: Bearer em_live_..."

# Replace its URL, events and on/off state (all three are required)
curl -X PUT https://api.euromail.dev/v1/webhooks/{id} \
  -H "Authorization: Bearer em_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/euromail",
    "events": ["sent", "bounced", "failed"],
    "is_active": true
  }'

# Delete it
curl -X DELETE https://api.euromail.dev/v1/webhooks/{id} \
  -H "Authorization: Bearer em_live_..."

The signing secret is not returned by these calls. A delete returns 204 No Content. All webhook calls need the webhooks:manage scope.

Dashboard Testing and Event Log

The dashboard's "Send test" button and the POST /v1/webhooks/{id}/test API endpoint both go through the same delivery pipeline as real events: the test event is signed the same way, POSTed to your endpoint, and recorded in the delivery history, so verifying against a test send is a true test of your signature check. A few things are deliberately different for a test send:

  • It carries "event": "test" and a fixed payload ({"data": {"message": "This is a test webhook event from EuroMail."}}) rather than real event data.
  • It does not count toward the 10-failure auto-deactivation threshold — a test against an endpoint you're still building is expected to fail sometimes, and shouldn't disable the webhook.
  • It is not retried on failure — you get one request per press.
  • It's rate-limited to 5 test sends per minute per webhook, shared across the dashboard button and the API endpoint.

The event log on the webhook's detail page shows every delivery attempt — success or failure, status code, response time, and (expandable) the request and response bodies — for both real and test events.

Send your first email in about 90 seconds

The free tier includes 3,000 emails a month. Email storage and AI processing in Finland, with a DPA on every plan.

Create free account See live delivery data