Email API — developer documentation

// Node.js 18+, no packages. Run after approval with server environment secrets.
// Sending is disabled at this docs release; production activation is separate.
// Persist the idempotency key WITH the business event before the first attempt.
// This makes one request; on an uncertain HTTP result reuse the unchanged body
// and key. Never resend an ambiguous message under a fresh key.
const apiKey = process.env.MAILCORE_API_KEY;
const idempotencyKey = process.env.MAILCORE_IDEMPOTENCY_KEY;
if (!apiKey || /[\r\n]/.test(apiKey)) throw new Error('Set MAILCORE_API_KEY on your server');
if (!/^[A-Za-z0-9._:-]{16,128}$/.test(idempotencyKey ?? '')) {
  throw new Error('Set the 16–128 character key saved with this application event');
}
const request = {
  from: process.env.MAILCORE_FROM ?? 'Example Shop <orders@notify.example>',
  to: process.env.MAILCORE_TO ?? 'customer@recipient.example',
  subject: 'Order #8421 completed',
  text: 'Your order has been completed.',
  tags: { order_id: '8421' },
};
if (request.from.includes('.example') || request.to.endsWith('.example')) {
  throw new Error('Set MAILCORE_FROM to your approved sender and MAILCORE_TO to the intended recipient');
}
try {
  const response = await fetch('https://mailcore.uz/api/email/v1/emails', {
    method: 'POST',
    redirect: 'error',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(request),
    signal: AbortSignal.timeout(30_000),
  });
  const result = await response.json();
  if (response.status !== 202) {
    console.error(JSON.stringify({ httpStatus: response.status, ...result }));
    process.exitCode = 1;
  } else {
    // Persist result.id on the same business event; poll GET /emails/{id}.
    console.log(JSON.stringify(result));
  }
} catch {
  // Do not log request bodies or keys. Acceptance may be uncertain after I/O.
  console.error('No usable HTTP result. Reconcile using the saved event key and unchanged payload.');
  process.exitCode = 1;
}

"""Python 3.10+, standard library. One attempt, only after project approval.

Sending is disabled at this docs release; production activation is separate.

Persist MAILCORE_IDEMPOTENCY_KEY with the application event BEFORE sending.
Reuse that key and unchanged payload after an uncertain HTTP result. Save the
returned id with the event. Never blindly resend an ambiguous message.
"""

import json
import os
import re
import sys
import urllib.error
import urllib.request


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None  # Never forward a Bearer key to a redirect destination.


def main():
    api_key = os.environ.get("MAILCORE_API_KEY", "")
    key = os.environ.get("MAILCORE_IDEMPOTENCY_KEY", "")
    if not api_key or "\r" in api_key or "\n" in api_key:
        raise SystemExit("Set MAILCORE_API_KEY in your server environment")
    if not re.fullmatch(r"[A-Za-z0-9._:-]{16,128}", key):
        raise SystemExit("Set the idempotency key saved with this application event")
    payload = {
        "from": os.environ.get("MAILCORE_FROM", "Example Shop <orders@notify.example>"),
        "to": os.environ.get("MAILCORE_TO", "customer@recipient.example"),
        "subject": "Order #8421 completed",
        "text": "Your order has been completed.",
        "tags": {"order_id": "8421"},
    }
    if ".example" in payload["from"] or payload["to"].endswith(".example"):
        raise SystemExit("Set MAILCORE_FROM to your approved sender and MAILCORE_TO to the recipient")
    request = urllib.request.Request(
        "https://mailcore.uz/api/email/v1/emails",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": "Bearer " + api_key,
            "Idempotency-Key": key,
            "Content-Type": "application/json",
        },
        method="POST",
    )
    try:
        with urllib.request.build_opener(NoRedirect()).open(request, timeout=30) as response:
            result = json.loads(response.read(1_048_577))
            if response.status != 202:
                raise ValueError("unexpected HTTP status")
            print(json.dumps(result))  # Persist id on the business event.
    except urllib.error.HTTPError as error:
        try:
            detail = json.loads(error.read(1_048_577))
        except (ValueError, OSError):
            detail = {"error": "unexpected_http_response"}
        print(json.dumps({"httpStatus": error.code, **detail}), file=sys.stderr)
        raise SystemExit(1)
    except (urllib.error.URLError, TimeoutError, OSError, ValueError):
        raise SystemExit("No usable HTTP result. Reconcile with the saved event key and unchanged payload.")


if __name__ == "__main__":
    main()

<?php
// PHP 8.1+ with HTTPS stream support. No Composer packages.
// Sending is disabled at this docs release; production activation is separate.
// Persist this idempotency key with the application event before sending.
// Reuse key + unchanged payload after an uncertain HTTP result. Save the
// returned id on the same event. Never resend an ambiguous message blindly.
declare(strict_types=1);

$apiKey = getenv('MAILCORE_API_KEY') ?: '';
$key = getenv('MAILCORE_IDEMPOTENCY_KEY') ?: '';
if ($apiKey === '' || preg_match('/[\r\n]/', $apiKey)) {
    fwrite(STDERR, "Set MAILCORE_API_KEY on your server\n");
    exit(1);
}
if (!preg_match('/^[A-Za-z0-9._:-]{16,128}$/D', $key)) {
    fwrite(STDERR, "Set the idempotency key saved with this application event\n");
    exit(1);
}
$payload = [
    'from' => getenv('MAILCORE_FROM') ?: 'Example Shop <orders@notify.example>',
    'to' => getenv('MAILCORE_TO') ?: 'customer@recipient.example',
    'subject' => 'Order #8421 completed',
    'text' => 'Your order has been completed.',
    'tags' => ['order_id' => '8421'],
];
if (str_contains($payload['from'], '.example') || str_ends_with($payload['to'], '.example')) {
    fwrite(STDERR, "Set MAILCORE_FROM to your approved sender and MAILCORE_TO to the recipient\n");
    exit(1);
}
$context = stream_context_create(['http' => [
    'method' => 'POST',
    'header' => "Authorization: Bearer {$apiKey}\r\nIdempotency-Key: {$key}\r\nContent-Type: application/json\r\n",
    'content' => json_encode($payload, JSON_THROW_ON_ERROR),
    'timeout' => 30,
    'ignore_errors' => true,
    'follow_location' => 0, // Do not forward the Bearer key on redirects.
], 'ssl' => ['verify_peer' => true, 'verify_peer_name' => true]]);
$result = @file_get_contents('https://mailcore.uz/api/email/v1/emails', false, $context, 0, 1048577);
if ($result === false) {
    fwrite(STDERR, "No usable HTTP result. Reconcile with the saved event key and unchanged payload.\n");
    exit(1);
}
$status = 0;
foreach ($http_response_header ?? [] as $header) {
    if (preg_match('/^HTTP\/\S+ (\d{3})/', $header, $match)) $status = (int) $match[1];
}
try {
    $document = json_decode($result, true, 512, JSON_THROW_ON_ERROR);
    if (!is_array($document)) throw new RuntimeException('Unexpected response');
    if ($status !== 202) {
        fwrite(STDERR, json_encode(['httpStatus' => $status] + $document, JSON_THROW_ON_ERROR) . "\n");
        exit(1);
    }
    echo json_encode($document, JSON_THROW_ON_ERROR) . "\n";
} catch (Throwable $error) {
    fwrite(STDERR, "No usable JSON result. Reconcile with the saved event key and unchanged payload.\n");
    exit(1);
}

// Node.js 22.13+; only built-in modules. Local receiver for integration testing.
// Put behind public HTTPS:443 in production; register it through the operator.
// Use a persistent inbox volume. The unique ID survives restarts; an application
// worker must apply business changes transactionally/idempotently from this
// inbox. Receipt here does NOT mean a business action has been performed.
import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';
import { DatabaseSync } from 'node:sqlite';
import { pathToFileURL } from 'node:url';

const EVENT_STATUSES = new Set(['accepted', 'delayed', 'delivered', 'bounced', 'complained', 'rejected', 'failed', 'ambiguous']);
const MAX_BODY = 65_536;

export function verifyWebhook(rawBody, headers, secret, { now = Math.floor(Date.now() / 1000), toleranceSeconds = 300 } = {}) {
  if (!Buffer.isBuffer(rawBody) || rawBody.length > MAX_BODY || typeof secret !== 'string' || !secret) {
    throw new Error('Invalid webhook input');
  }
  const normalized = new Map();
  for (const [name, value] of Object.entries(headers)) {
    const key = name.toLowerCase();
    if (!key.startsWith('webhook-')) continue;
    if (normalized.has(key) || (Array.isArray(value) && value.length !== 1)) throw new Error('Duplicate header');
    const text = Array.isArray(value) ? value[0] : value;
    if (typeof text !== 'string') throw new Error('Invalid header');
    normalized.set(key, text);
  }
  const id = normalized.get('webhook-id') ?? '';
  const timestamp = normalized.get('webhook-timestamp') ?? '';
  const signature = normalized.get('webhook-signature') ?? '';
  if (!/^evt_[a-f0-9]{24}$/.test(id) || !/^[0-9]+$/.test(timestamp) || !/^v1,[a-f0-9]{64}$/.test(signature)) {
    throw new Error('Invalid signed headers');
  }
  const seconds = Number(timestamp);
  if (!Number.isSafeInteger(seconds) || !Number.isFinite(now) || !Number.isFinite(toleranceSeconds) || toleranceSeconds < 0 || Math.abs(now - seconds) > toleranceSeconds) {
    throw new Error('Timestamp outside tolerance');
  }
  // Sign the raw bytes BEFORE parsing JSON. The literal secret is UTF-8 text,
  // not a base64-decoded key. Never stringify a parsed object for verification.
  const expected = createHmac('sha256', Buffer.from(secret, 'utf8'))
    .update(Buffer.from(`${id}.${timestamp}.`, 'ascii')).update(rawBody).digest();
  if (!timingSafeEqual(expected, Buffer.from(signature.slice(3), 'hex'))) throw new Error('Invalid signature');
  const event = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(rawBody));
  if (!event || typeof event !== 'object' || Array.isArray(event) || event.id !== id || typeof event.createdAt !== 'string' || Number.isNaN(Date.parse(event.createdAt))) {
    throw new Error('Invalid event');
  }
  const data = event.data;
  if (!data || typeof data !== 'object' || Array.isArray(data) || !/^eml_[a-f0-9]{24}$/.test(data.emailId ?? '') || !EVENT_STATUSES.has(data.status) || event.type !== `email.${data.status}` || !(data.detail === null || typeof data.detail === 'string')) {
    throw new Error('Invalid event data');
  }
  return event;
}

export function startReceiver() {
  const secret = process.env.MAILCORE_WEBHOOK_SECRET;
  if (!secret) throw new Error('Set MAILCORE_WEBHOOK_SECRET; never log it');
  const port = Number(process.env.PORT ?? 8080);
  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Invalid PORT');
  const inbox = new DatabaseSync(process.env.MAILCORE_WEBHOOK_INBOX ?? 'mailcore-webhook-inbox.sqlite3');
  inbox.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; CREATE TABLE IF NOT EXISTS inbox (id TEXT PRIMARY KEY, raw_body BLOB NOT NULL, received_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP);');
  const insert = inbox.prepare('INSERT OR IGNORE INTO inbox (id, raw_body) VALUES (?, ?)');
  const existing = inbox.prepare('SELECT raw_body FROM inbox WHERE id = ?');
  const server = createServer((req, res) => {
    const reply = (status, error) => {
      if (res.writableEnded) return;
      res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
      res.end(JSON.stringify(error ? { ok: false, error } : { ok: true }));
    };
    if (req.url !== '/mailcore-webhook') { req.resume(); reply(404, 'not_found'); return; }
    if (req.method !== 'POST') { req.resume(); res.setHeader('Allow', 'POST'); reply(405, 'method_not_allowed'); return; }
    if ((req.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase() !== 'application/json') {
      req.resume(); reply(415, 'content_type_required'); return;
    }
    const chunks = [];
    let length = 0;
    let rejected = false;
    req.on('data', chunk => {
      length += chunk.length;
      if (length > MAX_BODY) { rejected = true; chunks.length = 0; reply(413, 'body_too_large'); return; }
      if (!rejected) chunks.push(chunk);
    });
    req.on('error', () => reply(400, 'request_invalid'));
    req.on('end', () => {
      if (rejected) return;
      const rawBody = Buffer.concat(chunks);
      let event;
      try { event = verifyWebhook(rawBody, req.headersDistinct, secret); }
      catch { reply(401, 'webhook_invalid'); return; }
      try {
        // SQLite commits the unique inbox row before we acknowledge. Retain
        // IDs for your retry/recovery policy and monitor unprocessed backlog.
        insert.run(event.id, rawBody);
        if (!Buffer.from(existing.get(event.id).raw_body).equals(rawBody)) {
          reply(409, 'event_id_conflict'); return;
        }
        reply(200);
      } catch { reply(500, 'inbox_unavailable'); }
    });
  });
  server.requestTimeout = 10_000;
  server.headersTimeout = 10_000;
  server.listen(port, '127.0.0.1');
  return server;
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) startReceiver();

"""Python 3.10+, standard library. Local receiver; production needs HTTPS:443.

An operator configures the webhook. Persist the SQLite inbox on durable storage.
An application worker must apply business changes transactionally/idempotently
from this inbox. HTTP 200 acknowledges durable receipt, not a business action.
"""
import hashlib
import hmac
from contextlib import closing
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import math
import os
import re
import sqlite3
import time

MAX_BODY = 65_536
EVENT_STATUSES = {"accepted", "delayed", "delivered", "bounced", "complained", "rejected", "failed", "ambiguous"}


def verify_webhook(raw_body, headers, secret, *, now=None, tolerance_seconds=300):
    if not isinstance(raw_body, bytes) or len(raw_body) > MAX_BODY or not isinstance(secret, str) or not secret:
        raise ValueError("Invalid webhook input")
    normalized = {}
    for name, value in headers.items():
        key = name.lower()
        if not key.startswith("webhook-"):
            continue
        if key in normalized or (isinstance(value, (list, tuple)) and len(value) != 1):
            raise ValueError("Duplicate header")
        text = value[0] if isinstance(value, (list, tuple)) else value
        if not isinstance(text, str):
            raise ValueError("Invalid header")
        normalized[key] = text
    event_id = normalized.get("webhook-id", "")
    timestamp = normalized.get("webhook-timestamp", "")
    signature = normalized.get("webhook-signature", "")
    if not re.fullmatch(r"evt_[a-f0-9]{24}", event_id) or not re.fullmatch(r"[0-9]{1,13}", timestamp) or not re.fullmatch(r"v1,[a-f0-9]{64}", signature):
        raise ValueError("Invalid signed headers")
    current = time.time() if now is None else now
    if not math.isfinite(current) or not math.isfinite(tolerance_seconds) or tolerance_seconds < 0 or abs(current - int(timestamp)) > tolerance_seconds:
        raise ValueError("Timestamp outside tolerance")
    # Exact raw request bytes. The literal secret is UTF-8, not base64-decoded.
    signed = (event_id + "." + timestamp + ".").encode("ascii") + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature[3:]):
        raise ValueError("Invalid signature")
    event = json.loads(raw_body.decode("utf-8"))
    if not isinstance(event, dict) or event.get("id") != event_id or not isinstance(event.get("createdAt"), str):
        raise ValueError("Invalid event")
    data = event.get("data")
    if not isinstance(data, dict) or not isinstance(data.get("emailId"), str) or not re.fullmatch(r"eml_[a-f0-9]{24}", data["emailId"]):
        raise ValueError("Invalid email ID")
    status = data.get("status")
    if not isinstance(status, str) or status not in EVENT_STATUSES or event.get("type") != "email." + status or "detail" not in data or not (data["detail"] is None or isinstance(data["detail"], str)):
        raise ValueError("Invalid event data")
    return event


def main():
    secret = os.environ.get("MAILCORE_WEBHOOK_SECRET", "")
    if not secret:
        raise SystemExit("Set MAILCORE_WEBHOOK_SECRET; never log it")
    inbox_path = os.environ.get("MAILCORE_WEBHOOK_INBOX", "mailcore-webhook-inbox.sqlite3")
    with closing(sqlite3.connect(inbox_path)) as connection, connection:
        connection.execute("PRAGMA journal_mode=WAL")
        connection.execute("PRAGMA synchronous=FULL")
        connection.execute("CREATE TABLE IF NOT EXISTS inbox (id TEXT PRIMARY KEY, raw_body BLOB NOT NULL, received_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP)")

    class Receiver(BaseHTTPRequestHandler):
        # Quiet by default: never log bodies, tokens or webhook secrets.
        def log_message(self, format, *args):
            pass

        def respond(self, status, error=None):
            body = json.dumps({"ok": not bool(error), **({"error": error} if error else {})}).encode()
            self.send_response(status)
            self.send_header("Content-Type", "application/json")
            self.send_header("Cache-Control", "no-store")
            self.send_header("Content-Length", str(len(body)))
            self.send_header("Connection", "close")
            if status == 405:
                self.send_header("Allow", "POST")
            self.end_headers()
            if self.command != "HEAD":
                self.wfile.write(body)
            self.close_connection = True

        def do_POST(self):
            self.connection.settimeout(10)
            if self.path != "/mailcore-webhook":
                self.respond(404, "not_found")
                return
            if self.headers.get("Content-Type", "").split(";")[0].strip().lower() != "application/json":
                self.respond(415, "content_type_required")
                return
            # This small demo does not parse chunked transfer coding. A reverse
            # proxy must buffer/dechunk and supply one Content-Length header.
            lengths = self.headers.get_all("Content-Length", [])
            if self.headers.get("Transfer-Encoding") or len(lengths) != 1 or not re.fullmatch(r"[0-9]{1,10}", lengths[0]):
                self.respond(400, "content_length_required")
                return
            size = int(lengths[0])
            if size > MAX_BODY:
                self.respond(413, "body_too_large")
                return
            try:
                raw_body = self.rfile.read(size)
                if len(raw_body) != size:
                    self.respond(400, "request_invalid")
                    return
                signed_headers = {name: self.headers.get_all(name, []) for name in ("Webhook-Id", "Webhook-Timestamp", "Webhook-Signature")}
                event = verify_webhook(raw_body, signed_headers, secret)
            except (ValueError, UnicodeError, OSError, TypeError):
                self.respond(401, "webhook_invalid")
                return
            try:
                with closing(sqlite3.connect(inbox_path)) as connection, connection:
                    connection.execute("PRAGMA synchronous=FULL")
                    connection.execute("INSERT OR IGNORE INTO inbox (id, raw_body) VALUES (?, ?)", (event["id"], raw_body))
                    saved = connection.execute("SELECT raw_body FROM inbox WHERE id = ?", (event["id"],)).fetchone()[0]
                    if saved != raw_body:
                        self.respond(409, "event_id_conflict")
                        return
                # Transaction has committed. A repeat now safely acknowledges
                # the persisted ID; process the inbox separately and monitor it.
                self.respond(200)
            except sqlite3.Error:
                self.respond(500, "inbox_unavailable")

        def do_GET(self):
            self.respond(405, "method_not_allowed")

        do_PUT = do_DELETE = do_PATCH = do_OPTIONS = do_HEAD = do_TRACE = do_GET

    port = int(os.environ.get("PORT", "8080"))
    HTTPServer(("127.0.0.1", port), Receiver).serve_forever()


if __name__ == "__main__":
    main()

<?php
// PHP 8.1+ and the bundled SQLite3 extension; no Composer packages.
// Local demo: php -S 127.0.0.1:8080 webhook-php.php
// Production needs public HTTPS:443 plus operator registration and durable DB.
// Inbox receipt is durable. A worker must apply business actions from the inbox
// transactionally/idempotently; this handler does not perform those actions.
declare(strict_types=1);

function verifyWebhook(string $rawBody, array $headers, string $secret, ?int $now = null, int $toleranceSeconds = 300): array {
    if ($secret === '' || strlen($rawBody) > 65536) throw new RuntimeException('Invalid input');
    $normalized = [];
    foreach ($headers as $name => $value) {
        $key = strtolower($name);
        if (!str_starts_with($key, 'webhook-')) continue;
        if (array_key_exists($key, $normalized) || (is_array($value) && count($value) !== 1)) throw new RuntimeException('Duplicate header');
        $value = is_array($value) ? array_values($value)[0] : $value;
        if (!is_string($value)) throw new RuntimeException('Invalid header');
        $normalized[$key] = $value;
    }
    $id = $normalized['webhook-id'] ?? '';
    $timestamp = $normalized['webhook-timestamp'] ?? '';
    $signature = $normalized['webhook-signature'] ?? '';
    if (!preg_match('/^evt_[a-f0-9]{24}$/D', $id) || !preg_match('/^[0-9]{1,13}$/D', $timestamp) || !preg_match('/^v1,[a-f0-9]{64}$/D', $signature)) throw new RuntimeException('Invalid signed headers');
    if ($toleranceSeconds < 0 || abs(($now ?? time()) - (int) $timestamp) > $toleranceSeconds) throw new RuntimeException('Stale timestamp');
    // Exact bytes BEFORE JSON parsing. Use the literal secret as UTF-8 text.
    $expected = hash_hmac('sha256', $id . '.' . $timestamp . '.' . $rawBody, $secret);
    if (!hash_equals($expected, substr($signature, 3))) throw new RuntimeException('Invalid signature');
    $event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
    if (!is_array($event) || ($event['id'] ?? null) !== $id || !is_string($event['createdAt'] ?? null)) throw new RuntimeException('Invalid event');
    $data = $event['data'] ?? null;
    $statuses = ['accepted', 'delayed', 'delivered', 'bounced', 'complained', 'rejected', 'failed', 'ambiguous'];
    if (!is_array($data) || !is_string($data['emailId'] ?? null) || !preg_match('/^eml_[a-f0-9]{24}$/D', $data['emailId']) || !in_array($data['status'] ?? null, $statuses, true) || ($event['type'] ?? null) !== 'email.' . $data['status'] || !array_key_exists('detail', $data) || !($data['detail'] === null || is_string($data['detail']))) throw new RuntimeException('Invalid event data');
    return $event;
}

function respond(int $status, ?string $error = null): never {
    http_response_code($status);
    header('Content-Type: application/json');
    header('Cache-Control: no-store');
    if ($status === 405) header('Allow: POST');
    echo json_encode($error === null ? ['ok' => true] : ['ok' => false, 'error' => $error], JSON_THROW_ON_ERROR);
    exit;
}

// Safe to require this file from a local verification test without serving.
if (isset($_SERVER['SCRIPT_FILENAME']) && realpath($_SERVER['SCRIPT_FILENAME']) === __FILE__) {
    if (($_SERVER['REQUEST_URI'] ?? '') !== '/mailcore-webhook') respond(404, 'not_found');
    if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') respond(405, 'method_not_allowed');
    if (strtolower(trim(explode(';', $_SERVER['CONTENT_TYPE'] ?? '')[0])) !== 'application/json') respond(415, 'content_type_required');
    // Buffer/dechunk and reject duplicate signed headers at the reverse proxy;
    // PHP SAPI can overwrite duplicate headers before the application sees them.
    $rawBody = file_get_contents('php://input', false, null, 0, 65537);
    if ($rawBody === false) respond(400, 'request_invalid');
    if (strlen($rawBody) > 65536) respond(413, 'body_too_large');
    $secret = getenv('MAILCORE_WEBHOOK_SECRET') ?: '';
    if ($secret === '') respond(500, 'receiver_not_configured');
    try {
        $event = verifyWebhook($rawBody, [
            'Webhook-Id' => $_SERVER['HTTP_WEBHOOK_ID'] ?? '',
            'Webhook-Timestamp' => $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '',
            'Webhook-Signature' => $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '',
        ], $secret);
    } catch (Throwable $error) { respond(401, 'webhook_invalid'); }
    try {
        $inbox = new SQLite3(getenv('MAILCORE_WEBHOOK_INBOX') ?: 'mailcore-webhook-inbox.sqlite3');
        $inbox->enableExceptions(true);
        $inbox->busyTimeout(5000);
        $inbox->exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; CREATE TABLE IF NOT EXISTS inbox (id TEXT PRIMARY KEY, raw_body BLOB NOT NULL, received_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP);');
        $insert = $inbox->prepare('INSERT OR IGNORE INTO inbox (id, raw_body) VALUES (:id, :body)');
        $insert->bindValue(':id', $event['id'], SQLITE3_TEXT);
        $insert->bindValue(':body', $rawBody, SQLITE3_BLOB);
        $insert->execute(); // Autocommit completes before acknowledging.
        $query = $inbox->prepare('SELECT raw_body FROM inbox WHERE id = :id');
        $query->bindValue(':id', $event['id'], SQLITE3_TEXT);
        if ($query->execute()->fetchArray(SQLITE3_ASSOC)['raw_body'] !== $rawBody) respond(409, 'event_id_conflict');
        $inbox->close();
        respond(200); // Already persisted duplicates also acknowledge safely.
    } catch (Throwable $error) { respond(500, 'inbox_unavailable'); }
}