Register an inbound HMAC-signed webhook
POST /v1/webhooks
Register an inbound webhook. Accepts a client-supplied idempotency key (Idempotency-Key header or client_id body field): a retry with the same key replays the original registration; the same key with a different body is a 409. New keys should grant webhook:write; mailbox:read remains accepted for older keys. Connection mutations always require webhook:write. The registration retains its resource boundary after the connection expires. An explicit inbox binds its stable ID. Without an inbox filter, selected-inbox connections bind their selected IDs and broader connections bind the current project or organization.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Select an organization within the connection grant.
Narrow to a project within the connection grant.
Header Parameters
Section titled “Header Parameters ”Optional client-supplied key making a CREATE exactly-once. A retry with the same key returns the ORIGINAL response (same status + body) instead of creating a duplicate; the same key with a different request body returns 409. The body field client_id is honored as an alias when this header is absent. The key is scoped per tenant (and per agent on the agent plane), so keys never collide across callers.
Request Body required
Section titled “Request Body required ”object
AgentMail-compatible alias for events.
Scope to one mailbox; omit for all.
Legacy alias for inbox.
Optional idempotency key (alias for the Idempotency-Key header). A retry with the same key replays the original webhook registration.
Responses
Section titled “ Responses ”Registered. secret is shown once.
A webhook registration. secret is present only on the create response (shown once); list/get redact it. The durable resource_scope defines the delivery boundary. inbox is an additional address filter; null removes that filter without widening selected stable inbox IDs. Registrations survive the creating connection’s expiry and must be deleted separately.
object
Agent identity recorded at creation.
Agent-owned inboxes for legacy keys; stable selected inbox IDs, project, or organization for connections. Project and organization scopes include future inboxes.
Stable inbox IDs for an inboxes-scoped registration.
Creating connection ID when applicable.
HMAC signing secret. Create response only.
Invalid request.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.
Missing or invalid credential.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.
The supplied idempotency key was already used with a different request body (error = idempotency_conflict).
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.