Webhooks
InboxOps receives webhooks from Microsoft (Graph change notifications and lifecycle) and Gmail (Pub/Sub push) to ingest mail and subscription events. These endpoints are public (no Bearer token); verification is done via provider-specific mechanisms.
Internal / not publicly documented in full: Exact payload shapes and internal job names are omitted for security. Below is what integrators need to know about purpose and verification.
Microsoft Graph
GET /v1/webhooks/microsoft
Purpose: Subscription validation. Microsoft sends a validationToken query parameter; the API echoes it back in the response body (plain text) to confirm ownership. No auth.
Example: Microsoft calls GET /v1/webhooks/microsoft?validationToken=.... Respond with the same token.
POST /v1/webhooks/microsoft
Purpose: Change notifications (new mail, folder changes). When MICROSOFT_WEBHOOK_SECRET is set, the request is verified using clientState in the body (must match the secret). The API parses the notification and enqueues internal processing. Respond with 202 or 200 quickly; do not block on processing.
Retry: Microsoft retries according to Graph subscription lifecycle. No custom retry contract is documented here.
POST /v1/webhooks/microsoft/lifecycle
Purpose: Lifecycle events (e.g. reauthorization required, subscription removed, missed notifications). When MICROSOFT_WEBHOOK_SECRET is set, the x-webhook-secret header must match. Respond with 202. Renewal and re-subscription are handled by the product; no action required from callers.
Gmail
POST /v1/webhooks/gmail
Purpose: Gmail Pub/Sub push. The request is verified using JWT in the Authorization: Bearer header (signed by Google; audience matches the push endpoint URL). The body is a Pub/Sub envelope (e.g. message.data base64-encoded). The API parses it and enqueues sync work.
Retry: Google Pub/Sub retries according to its policy. Standard provider retries apply.
Summary
| Endpoint | Method | Verification | Purpose |
|---|---|---|---|
| /v1/webhooks/microsoft | GET | validationToken echoed | Subscription validation |
| /v1/webhooks/microsoft | POST | clientState (if secret set) | Change notifications |
| /v1/webhooks/microsoft/lifecycle | POST | x-webhook-secret (if set) | Lifecycle events |
| /v1/webhooks/gmail | POST | JWT Bearer (Google) | Pub/Sub push |
Do not expose MICROSOFT_WEBHOOK_SECRET or any signing keys in client code. Webhook endpoints are intended for provider-to-InboxOps communication only.