Skip to main content
When an email arrives at one of your inboxes — or when the reputation engine suspends or reactivates an inbox or pod — OpenMail delivers the event to your webhook URL as an HTTP POST request. See Events for the full list.

​
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:

​
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: 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.