Register an inbound HMAC-signed webhook

POST

/v1/webhooks

• Production
• Local

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.

Authorizations

• AgentKey
  webhook:write
• AgentKey
  mailbox:read

Parameters

Header Parameters

Idempotency-Key

string

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

object

url

required

string format: uri

events

Array<string>

Allowed values: message.received

event_types

AgentMail-compatible alias for events.

Array<string>

Allowed values: message.received

inbox

Scope to one mailbox; omit for all.

string

address

Legacy alias for inbox.

string

client_id

Optional idempotency key (alias for the Idempotency-Key header). A retry with the same key replays the original webhook registration.

string

Responses

201

Registered. secret is shown once.

A webhook registration. secret is present only on the create response (shown once); list/get redact it. inbox is null when the webhook covers every inbox.

object

id

string

url

string

events

Array<string>

Allowed values: message.received

inbox

string

nullable

agent_id

Agent that owns the webhook.

string

secret

HMAC signing secret. Create response only.

string

secret_prefix

string

active

boolean

created_at

string format: date-time

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

409

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

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope