Polling is simple, but it can waste requests and delay a workflow. Relay webhooks let an application receive an event when an inbox changes, then fetch the message through an authorized API call. The result is faster automation without putting message content directly into an unverified callback.
The reliable webhook pattern
Relay inbox -> signed event -> your endpoint -> verify signature
|
-> fetch message -> process once
The callback should acknowledge quickly, verify the signature before processing, and use the event ID as an idempotency key. If the same event arrives twice, the second delivery should be harmless. Keep the raw event small and fetch the full message only when the event matches an inbox and workflow you expect.
| Concern | Recommended control |
|---|---|
| Forgery | Verify the webhook signature |
| Duplication | Store processed event IDs |
| Slow processing | Queue after acknowledgement |
| Secret leakage | Keep signing secrets out of logs |
| Untrusted mail | Sanitize before rendering |
Configure webhooks through the API documentation or the official SDK. Test your handler with a dedicated inbox and a staging endpoint before sending events to production. For local development, use a secure tunnel and rotate the signing secret after experiments. The CLI guide is useful for replaying a delivery scenario while you debug the receiver.
Do not confuse delivery with verification
A webhook tells you that an event occurred. It does not prove that a message is the one your test expected, that a link is safe, or that a sender is trustworthy. Match the inbox, subject, sender, and message ID, then apply the workflow's own assertions.
Frequently asked questions
Should a webhook contain the full email body?
Prefer an event reference and fetch the authorized message when needed.
What if my endpoint is temporarily down?
Build for retries and idempotency; never assume one network attempt is the only attempt.
Can I still poll?
Yes. Polling remains useful for short scripts and fallback diagnostics.
Local tunnel checklist
| Step | Pass criteria |
|---|---|
| Register HTTPS endpoint | TLS cert valid |
| Verify signature | Reject mutated body |
| Return 2xx quickly | Queue heavy work |
| Replay same event ID | No duplicate side effect |