Bridge Email-Only Alerts into Webhooks Reliably

Use a dedicated ingestion boundary

Send legacy application alarms to a dedicated address or mailbox. Restrict who can submit messages through an authenticated channel or validate trusted provider authentication results with the intended sender-domain policy. A display name or raw From header alone can be spoofed.

Limit accepted message size, attachment handling, and parsing time. Treat the body as untrusted input. A webhook bridge should not execute an attached script or render arbitrary HTML to extract a severity. Keep raw messages in restricted storage only for the retention needed to investigate parsing failures.

Define the normalized event

{
  "source": "legacy-backup",
  "event_key": "prod-catalog:nightly-backup",
  "event_state": "firing",
  "message_id": "provider-message-1842",
  "observed_at": "2026-09-12T04:05:00Z",
  "received_at": "2026-09-12T04:05:09Z",
  "summary": "Nightly backup verification failed"
}

This is a bridge-internal example; map it to the receiving provider's supported schema. Keep message identity for deduplicating email delivery. Use a separate stable event key for updating one incident across several messages. A new message ID every five minutes should not create a new incident every five minutes.

Require explicit parsing rules for firing and recovery. If the old application sends only failure mail, do not invent recovery after a period of silence. Mark recovery as manual or connect a separate current-state check. Quarantine messages that no longer match the expected format and alert on parser failures.

Persist before moving the cursor

Poll the mailbox with a stored cursor, or use a supported push-notification interface. For Gmail, push notifications (opens in a new tab) require watch renewal; Google documents renewal at least every seven days and recommends daily renewal. Record the returned expiration and monitor it.

A push notification indicates mailbox changes to retrieve. Fetch and normalize the relevant messages, durably store pending webhook work, and then advance the ingestion cursor. Delivery workers retry the stored work using a stable idempotency or incident key where the receiver supports it. If the bridge restarts between steps, it should replay safely rather than lose the alert.

Account for delayed or missed push notifications with periodic reconciliation. If a provider cursor is no longer usable, follow its supported resynchronization process and deduplicate recovered messages.

Make the bridge observable

Track the last successful mailbox scan, oldest unprocessed message, oldest pending webhook, parser rejection count, and successful receiver acceptance. An empty queue is meaningful only when ingestion is fresh. A crashed mailbox reader can leave an empty queue forever.

Use an outside deadline for the bridge's own reporting. Keep its critical failure notification independent of the inbox and webhook path being tested where practical.

Test exactly-once intent with at-least-once delivery

Replay one email twice, deliver a recovery before an older failure, expire the test mailbox credential, restart after persisting work, and return a temporary webhook error. Confirm no alert is lost and duplicates update the intended incident. Record any receiver limitation explicitly; if it lacks idempotency, the bridge needs a documented reconciliation strategy rather than a claim of exactly-once delivery.