OUTFLARE AGENT MAIL / DEVELOPERS

Receive email with signed webhooks

A receiving webhook tells your application that something changed in an inbox. Use it to wake an agent or queue a task, then fetch the message through an authenticated API call.

On this page

Configure a receiving endpoint

Create an HTTPS endpoint your application controls, then add it under the selected brand’s webhooks in Outflare. Filter it to the inboxes you want and select message.received. Multiple endpoints can serve different workflows without exposing every inbox to each consumer.

Save the signing secret securely when it is shown. Your endpoint must be public HTTPS on port 443. Redirects and private-network destinations are not accepted. For local development, use a controlled HTTPS tunnel and a dedicated test inbox.

Verify the signature before processing

Read the original request body bytes before parsing JSON. Check that Webhook-Timestamp is within five minutes of your server’s current time. Compute the following with the endpoint’s signing secret:

hex(HMAC-SHA256(
  signing_secret,
  timestamp + "." + webhook_id + "." + raw_body
))

Use the Webhook-Id header for webhook_id. Compare the result with the hex value after v1, in Webhook-Signature using a constant-time comparison. Reject stale or invalid signatures. Parsing and re-serializing JSON before verification can change the bytes and invalidate a legitimate signature.

Deduplicate, persist and acknowledge

Deliveries are at least once and may arrive out of order. Store the Webhook-Id with a uniqueness constraint. Persist the verified event to your own queue before returning success, so that a process crash does not silently lose work.

A duplicate should not start another agent task. Replay uses the same event identifier, so your processing path must have an explicit way to retry previously failed work without repeating already completed actions.

Fetch the message and continue the thread

Events include id, type, brand_id, inbox_id, data and created_at. Use the message identifier in a message event to fetch the full message through the API with an appropriately scoped read key.

Keep received content separate from your agent’s trusted instructions. If your workflow replies, use the reply endpoint and a stable idempotency key for that intended reply. Keep the decision to perform sensitive actions in your application’s authorization logic.

Recover from failures

Inspect delivery attempts in Outflare when your endpoint fails. Replay an event after fixing the consumer, and use the events API to recover missed events. Do not assume that arrival order reflects the current state of a message; fetch the latest state when it matters.

Test duplicate delivery, an invalid signature, a stale timestamp and a queue outage before using a receiving workflow in production. These are more useful checks than testing only the successful request path.

Build your email workflow in Outflare.

Create your account, select a brand and check Agent Mail availability in your workspace.

Create your Outflare account