/webhooks/{id}

PATCH/v1/agent/webhooks/{id}

Update a webhook endpoint

Requires API-key authentication (agentAuth, agentId).

Purpose: update an outbound webhook endpoint.

Auth and scope: header-key auth or OAuth agent:webhooks:manage.

Idempotency: required.

Path params:

json

example

{
  "id": "webhook endpoint uuid"
}

Request:

json

example

{
  "url": "https://example.com/hightop/webhook",
  "description": "Updated webhook",
  "event_types": ["payment.executed"],
  "enabled": true
}

At least one field is required. event_types accepts only currently subscribable event types. If an endpoint was auto-disabled for sustained failures, enabled: true is owner-only and returns owner_only_action.

Response:

json

example

{
  "ok": true,
  "webhook": {
    "id": "uuid",
    "url": "https://example.com/hightop/webhook",
    "description": "Updated webhook",
    "event_types": ["payment.executed"],
    "enabled": true,
    "disabled_reason": null,
    "consecutive_failures": 0,
    "last_delivered_at": null,
    "last_failure_at": null,
    "created_at": "2026-05-16T00:00:00.000Z",
    "updated_at": "2026-05-16T00:05:00.000Z"
  }
}

Common errors: validation_failed, not_found, owner_only_action, idempotency_key_reuse_mismatch, insufficient_scope.

Related recipe: Verify a Webhook.