Skip to main content
When an email arrives at one of your inboxes, OpenMail delivers it to your webhook URL as an HTTP POST request.

​
Why use webhooks?

Instead of constantly polling the API to check for new emails, you register a URL and OpenMail sends a POST request as soon as an event happens. This event-driven approach is more efficient and lets you build responsive agents that react instantly to incoming messages.
  • Real-time - Build agents that reply to emails in seconds.
  • Efficient - No polling; saves compute and simplifies your logic.

​
Delivery semantics

  • At-least-once delivery - We may deliver the same event more than once. Use event_id to deduplicate.
  • No ordering guarantee - Events may arrive out of order. Use occurred_at to sort if needed.

​
Webhook headers

Every POST includes:
HeaderDescription
X-Event-IdStable UUID for this event. Same across retries. Use for deduplication.
X-TimestampUnix timestamp of the delivery attempt
X-SignatureHMAC-SHA256 signature for verification

​
Signature verification

The signature is computed as HMAC-SHA256(webhook_secret, "{timestamp}.{raw_json_payload}"). Verify before processing. Use constant-time comparison to prevent timing attacks. Also verify that X-Timestamp is within 5 minutes of current time to prevent replay attacks.

​
Retry policy

If your endpoint doesn’t return 2xx within 15 seconds:
AttemptDelay
1Immediate
230 seconds
360 seconds
42 minutes
54 minutes
After 5 failed attempts, the event is marked as failed.

​
Full payload and verification

Events

Payload structure and field descriptions.

Verification

HMAC signature verification and code examples.

Setup

Configure your endpoint and implement the handler.