Wake your runtime when the agent inbox changes.
Use a signed webhook to tell infrastructure you operate that a mailbox has new activity. The event carries a synchronization signal, not an email body or a credential.
For developers who operate an agent runtime and need a low-latency signal that an agent mailbox changed.
Configure a receiver and verify it before enabling delivery
Your receiver must verify signed requests and persist event IDs before returning success.
Prepare a public HTTPS receiver
Build a listener that accepts the Connect event, verifies the signature and timestamp, deduplicates event IDs, and durably records the event before returning success.
Save the endpoint from mailbox settings
In Settings → Inbox webhook, save the listener URL and copy the signing secret when Connect displays it. The secret is shown once; store it in your receiver’s secret manager.
Implement the verification challenge
When Connect sends
webhook.verify, validate its signed request and return a 2xx response that echoes theX-Connect-Challengeheader.Enable and run a test
After Connect confirms the endpoint, enable delivery and send a test. Confirm your worker receives and records the event, then uses its existing MCP or API authorization to discover mail.
The notification wakes your software; it does not read mail.
An inbox event includes an ID, mailbox ID, opaque revision, and notification token. It does not include addresses, subject lines, attachments, message content, or API credentials. Your runtime authenticates to Connect with its existing authorization and then lists messages.
- Verify HMAC-SHA256 over `id.timestamp.raw_request_body` using the decoded base64url secret bytes.
- Reject timestamps outside five minutes, compare signatures in constant time, and deduplicate by event ID.
- Return success only after durable event acceptance; Connect may retry a delivery.
Use the event as a wake-up, with polling as a safety net.
Delivery can be repeated and ordering is not guaranteed. Process the event idempotently, respect the notification token’s one-time discovery behavior, and keep a slower authenticated poll to recover from paused endpoints or missed notifications.
- The token allows one discovery read; it does not replace API or MCP authentication.
- Respect `poll_after_seconds`, 429 responses, and `Retry-After`.
- Check your mailbox Settings for current webhook availability.
Building a receiver that handles retries safely
Does the webhook include the email body?
No. It contains mailbox synchronization metadata and a short-lived discovery token. Your authenticated runtime fetches messages through the existing Connect API or MCP tools.
Can Connect execute my agent when the webhook arrives?
No. Connect delivers the wake-up event to the receiver you operate. Your own infrastructure decides whether and how to start the agent.
Is delivery exactly once and ordered?
No. Delivery is at least once and ordering is not guaranteed. Deduplicate event IDs, make processing idempotent, and retain backup polling.
Can an agent configure its own webhook?
No. A human mailbox owner configures the URL, verifies the receiver, enables delivery, and controls the signing secret.
Connect an inbox event to your runtime
Implement the signed receiver, then verify and enable it from the human-controlled mailbox settings.
Open webhook settings