Question 1

What are email webhooks and what events does Inbox OSS deliver?

Accepted Answer

Email webhooks are HTTP POSTs your application receives whenever something happens to a message you sent — delivered, opened, clicked, bounced, complained, unsubscribed, deferred, dropped, processed, and more. The Inbox OSS webhook system delivers **29 distinct event types** covering the entire transactional and marketing lifecycle: processed (accepted into our queue), delivered (successful SMTP delivery), opened (tracking pixel loaded), clicked (link click tracked), bounced (permanent failure), deferred (transient failure being retried), spam-reported (FBL complaint), unsubscribed (one-click or preference center), and 21 others including FBL-routed complaints, validation outcomes, and automation step entries.

Question 2

How are webhook payloads signed and how do I verify them?

Accepted Answer

Webhook payloads are signed with **Ed25519** by default. Each request includes two headers: X-Inbox-Signature (base64-encoded Ed25519 signature) and X-Inbox-Timestamp (Unix seconds when we signed it). The signed payload is the literal string `timestamp + "." + raw_body`. To verify: reconstruct that string, then verify the signature against our published public key using any standard Ed25519 library — tweetnacl in Node.js, PyNaCl in Python, golang.org/x/crypto/ed25519 in Go, libsodium in PHP and Rust. Reject requests where the timestamp is more than 5 minutes old to prevent replay attacks. The public key is shown in your dashboard webhook settings and rotates quarterly with 30-day overlap to allow zero-downtime cutover.

Question 3

Why Ed25519 instead of HMAC-SHA256 like SendGrid?

Accepted Answer

Ed25519 is an **asymmetric signature scheme** — we sign with a private key, you verify with the corresponding public key. This is structurally better than HMAC because the verification key in your application code is not a secret: if your server is compromised and the public key leaks, an attacker cannot forge new webhooks. HMAC requires that the same secret live in both our signing infrastructure and your application code; a leak on either side breaks the entire signature system. Ed25519 also produces shorter signatures (64 bytes vs. 32+ for HMAC) and is faster to verify on modern CPUs. For SendGrid migration, we additionally support HMAC-SHA256 on a compatibility endpoint so you can run both schemes in parallel during cutover.

Question 4

What happens when my webhook endpoint returns a non-2xx response?

Accepted Answer

Failed deliveries retry with **exponential backoff for 24 hours** on any non-2xx response. The retry schedule is roughly: immediate retry, then 30s, 2min, 10min, 30min, 1hr, 2hr, 4hr, 8hr, 16hr, with each retry carrying an X-Inbox-Webhook-Attempt header so your handler can detect duplicates. After 24 hours we mark the delivery as failed and surface it in the dashboard's webhook log for manual replay. Permanent failures (4xx responses that indicate a misconfigured endpoint) reduce the retry budget — a 410 Gone, for example, stops retries immediately. This is more aggressive than SendGrid (which gives up after fewer attempts) and gives you a wider safe-failure window during downstream maintenance.

Question 5

Can I replay webhook events manually from the dashboard?

Accepted Answer

Yes. The webhook log retains every event for **24 hours of retry history**, and the dashboard exposes a replay UI to re-fire any single event or any batch of events by time window, event type, message ID, or recipient. Replay is a true re-POST to the configured endpoint with a fresh signature and a new X-Inbox-Webhook-Replay header so your handler can opt-in to special replay logic (e.g., idempotency-key dedup, or skipping side effects you already executed). For longer retention, configure the webhook firehose to dump every event to S3 or BigQuery and replay from there — events stay queryable indefinitely.

Question 6

How do I subscribe to only specific event types?

Accepted Answer

Each webhook endpoint can be configured to receive any subset of the 29 event types. Common patterns include subscribing one endpoint to delivery-success events (delivered, opened, clicked) and a separate endpoint to failure events (bounced, deferred, spam-reported), or routing all events of a given category to a dedicated handler. Multiple endpoints can subscribe to overlapping event sets — fan-out is supported with independent retry state per endpoint. Event filtering also supports per-category filters, so you can subscribe an endpoint to only events from messages tagged with category=billing, for example.

Question 7

Are webhook payloads documented as JSON Schema?

Accepted Answer

Yes. Every one of the 29 event types has a **published JSON Schema** describing the exact payload shape — required and optional fields, types, enums, and constraints. The schemas are available at /docs/webhooks/schema as JSON files; you can run them through any JSON Schema codegen tool (datamodel-codegen for Python, json-schema-to-typescript, quicktype for Go/Rust/Swift) to generate type-safe webhook handlers. This is meaningfully better than SendGrid, which documents events only as informal examples without a machine-readable schema. Schema versions follow semver — breaking changes require a major version bump and 90-day deprecation notice.

Question 8

How much volume can webhook endpoints sustain?

Accepted Answer

There is no hard cap on webhook delivery volume per endpoint. Practical throughput is determined by your endpoint's ability to accept and 2xx-respond to incoming POSTs — most well-built endpoints handle 500-2000 events per second comfortably. For accounts sending millions of messages per day, the recommended pattern is to terminate webhooks at a lightweight HTTP layer (NGINX, Caddy, a managed API gateway, or a serverless function) that 200-responds immediately and enqueues the payload to a downstream worker pool. The webhook system delivers in parallel with up to 8 concurrent in-flight POSTs per endpoint, so backpressure on your endpoint translates to natural rate limiting rather than dropped events.

Question 9

How are custom_args preserved through to webhook events?

Accepted Answer

Every custom_args key set on the original /api/v1/mail/send request is preserved verbatim through to every webhook event for that message. So if you stamped the send with custom_args.user_id=42 and custom_args.order_id=7891, every delivered, opened, clicked, and bounced event for that message will include both keys. This is the standard pattern for stitching events back to internal records: stamp your business identifiers on the send, then route events back to your application by reading custom_args in the webhook handler. The metadata flows through SMTP submissions too — set X-INBOX-Custom-Arg-user_id: 42 on the outbound message and it surfaces identically.

Question 10

Is there a sandbox or test mode for webhooks during development?

Accepted Answer

Yes. The dashboard includes a **webhook test panel** that lets you fire any of the 29 event types as a synthetic event to your endpoint with a real Ed25519 signature so your verification logic gets exercised end-to-end. For local development, use a tunnel service (ngrok, Cloudflare Tunnel, Tailscale Funnel) to expose your localhost endpoint to our delivery infrastructure. We also publish a webhook-receiver reference implementation in Node.js, Python, and Go in our docs repository — it handles signature verification, idempotency, and retry-aware dedup out of the box and is a useful starting template.

Real-time events, signed and replayable

29 event types

Signed payloads

Smart retries

Replay UI

Event filtering

Typed schemas

Frequently asked questions about email webhooks

Wire your events in 5 minutes.