Webhook Events Reference¶

Mailyte sends webhooks for significant events across the mail server. Each delivery is an HTTP POST with a JSON payload, signed with HMAC-SHA256. The canonical dispatcher is shared/webhook_dispatcher.py; the full event-name catalogue is its Events class.

Envelope Structure¶

Every webhook, regardless of event type, follows this envelope:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "email.delivered",
  "timestamp": "2026-03-28T10:00:00.000000+00:00",
  "source": "log_ingestor",
  "org_id": 42,
  "domain": "acme.com",
  "tags": ["campaign:q1-newsletter"],
  "user_variables": {
    "order_id": "ORD-9901"
  },
  "data": {
    "...event-specific fields..."
  },
  "metadata": {},
  "signature": {
    "timestamp": 1743158400,
    "token": "a3f8c1d2e9b047...",
    "signature": "e3b0c44298fc1c..."
  }
}

Signature Verification¶

Method 1 — Full body HMAC (recommended)¶

Every request includes these headers:

Content-Type:        application/json
X-Webhook-Id:        550e8400-e29b-41d4-a716-446655440000
X-Webhook-Signature: sha256=<hex>
X-Webhook-Event:     email.delivered
X-Webhook-Source:    log_ingestor
X-Webhook-Timestamp: 2026-03-28T10:00:00.000000+00:00
User-Agent:          Mailyte-Webhook/2.0

X-Webhook-Signature is sha256= + HMAC-SHA256 (hex) of the raw request body, keyed with WEBHOOK_SECRET. If no secret is configured the header value is sha256= with an empty digest — always configure a secret in production.

Verify in Python:

import hmac, hashlib


def verify_signature(raw_body: bytes, header: str, secret: str) -> bool:
    expected = (
        "sha256="
        + hmac.new(
            secret.encode("utf-8"),
            raw_body,
            hashlib.sha256,
        ).hexdigest()
    )
    return hmac.compare_digest(expected, header)

Verify in PHP:

function verifySignature(string $rawBody, string $header, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $header);
}

Method 2 — Inline signature block (replay-attack protection)¶

The signature object in the payload is HMAC-SHA256 of str(timestamp) + token keyed with the same secret. Check it and reject stale events:

import hmac, hashlib, time


def verify_inline(payload: dict, secret: str, max_age_seconds: int = 900) -> bool:
    sig_block = payload.get("signature", {})
    ts = sig_block.get("timestamp", 0)
    token = sig_block.get("token", "")
    claimed_sig = sig_block.get("signature", "")

    # Reject stale events (default: older than 15 minutes)
    if abs(time.time() - ts) > max_age_seconds:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        (str(ts) + token).encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, claimed_sig)

Delivery Behavior¶

Return 406 to permanently decline an event type. All other non-2xx codes trigger a retry.

Event Catalogue¶

The Events class defines 163 event names. The tables below list them by category. Events marked ✗ are defined in the catalogue but not yet emitted by any code path — they are reserved names; do not build integrations that wait for them.

Email — Delivery Lifecycle¶

Emitted by the log ingestor as it parses Postfix logs (one event per final delivery attempt), and by the webhooks service for raw inbound/outbound notifications.

Delivery lifecycle payload (email.delivered / bounced / deferred / rejected)¶

The log ingestor sends the same data shape for all four:

{
  "message_id": "<abc123@acme.com>",
  "queue_id": "8A3F2B1C",
  "sender": "noreply@acme.com",
  "from": "noreply@acme.com",
  "subject": "Your order is confirmed",
  "html": "<html>...captured body if available...</html>",
  "text": "...captured body if available...",
  "recipient": "user@example.com",
  "to": "user@example.com",
  "domain": "acme.com",
  "organization_id": "01J5X8...",
  "status": "delivered",
  "relay": "gmail-smtp-in.l.google.com[142.250.x.x]:25",
  "dsn": "2.0.0",
  "size": 14580,
  "detail": "250 2.0.0 OK  1743158400 x9-2002si",
  "timestamp": "2026-03-28T10:00:00"
}

html/text come from the email_bodies capture table when body capture is enabled; detail carries the remote server's full response (bounce reason for failures).

email.inbound payload¶

{
  "message_id": "<ext456@external.com>",
  "from": "sender@external.com",
  "to": "inbox@acme.com",
  "subject": "Re: Project update",
  "size": 9840,
  "has_attachments": false,
  "spam_score": 1.2,
  "tls_used": true,
  "spf_result": "pass",
  "dkim_result": "pass",
  "dmarc_result": "pass"
}

Tracking¶

Payload keys: email_id, recipient, ip_address, user_agent (+ url for clicks; email, reason for unsubscribes).

IMAP / POP3 User Actions¶

Emitted by the webhooks service from Dovecot activity (source dovecot).

Delivery Complaints & Spam¶

Storage¶

storage.quota.* payload¶

{
  "entity_type": "mailbox",
  "identifier": "user@acme.com",
  "storage_type": "total",
  "current_usage": 4563402752,
  "quota_limit": 5368709120,
  "usage_percentage": 85.0
}

Authentication & Security¶

Rate Limiting¶

Queue Management¶

Health & Monitoring¶

Mailbox / Domain / Alias Admin¶

All emitted by the API on the corresponding admin operation.

Filters, Transport Rules, Shared Mailboxes¶

Migration¶

AI / RAG, Encryption, Archive, Delivery Optimizer¶

Compliance, White-Label & Reseller¶

Reserved Groups (defined, nothing emits them)¶

These whole categories exist in the catalogue only:

• Sieve & vacation: sieve.script.updated, sieve.script.activated, vacation.enabled, vacation.disabled, vacation.response.sent
• Backup & restore: backup.started, backup.completed, backup.failed, restore.started, restore.completed, restore.failed — backup state is surfaced through Prometheus gauges instead (see Prometheus Metrics)
• URL protection: url.rewritten, url.blocked, url.sandbox.result
• Webhook meta: webhook.delivery.failed (final failures land in the webhook_dead_letters table instead)

Webhook System (Meta)¶

Idempotency¶

Each event has a unique id (UUID4). Store processed IDs to safely handle duplicate deliveries — network retries can deliver the same event more than once.

processed_ids = set()


def handle_webhook(payload: dict):
    event_id = payload["id"]
    if event_id in processed_ids:
        return  # Already handled
    processed_ids.add(event_id)
    process(payload)

Dispatching Events (Server-Side)¶

From any service, fire an event with optional tags and user_variables:

from shared.webhook_dispatcher import dispatch_event, Events

dispatch_event(
    event_type=Events.EMAIL_DELIVERED,
    data={
        "message_id": "<abc@acme.com>",
        "recipient": "user@example.com",
    },
    org_id=42,
    domain="acme.com",
    tags=["transactional", "campaign:welcome"],
    user_variables={"user_id": "usr_9901"},
)

Services in the mailer tier (log_ingestor, Postfix/Dovecot scripts) pass use_redis=True, publishing to the mailyte:webhooks Redis channel; the webhooks service subscribes and performs the actual delivery.

Non-Canonical Webhook Paths¶

Two additional senders exist with different envelopes and event names — don't confuse them with the catalogue above:

• The webhooks service's notification sender delivers to per-organization endpoints from the webhook_urls table with events rate_limit.quota_alert, rate_limit.limit_exceeded, email.smtp.inbound, email.smtp.outbound, envelope {"event", "timestamp", "payload"} (optionally Fernet-encrypted), and its own retry policy (defaults: 3 retries, linear backoff).
• The monitoring service's webhook notifier sends health.service.status_change, health.system.<type>, health.recovery.<action>, health.summary.periodic to HEALTH_WEBHOOK_URLS.