Update a webhook (url, events, inbox filter, active)

PATCH

/v1/webhooks/{id}

• Production
• Local

Authorizations

• AgentKey
  webhook:write
• AgentKey
  mailbox:read

Parameters

Path Parameters

id

required

string

Request Body ^required

PATCH body for a webhook. Every field is optional; an omitted field leaves the stored value unchanged (PATCH semantics). The signing secret and id are immutable. inbox empty-string clears the per-inbox filter (covers all inboxes the agent owns).

object

url

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; empty string clears the filter.

string

address

Legacy alias for inbox.

string

active

Enable or disable delivery without deleting.

boolean

Responses

200

Updated (secret redacted).

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

404

Resource not found.

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