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.

​
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

See the Webhooks guide for the complete message.received payload structure and signature verification code examples.