Robots Center Agents Network
Log in Create workspace
Skip to content

API reference

Operator - Webhooks

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

8
GET
/api/v1/operator/webhook_subscriptions Web Session

List webhook subscriptions

Description

Returns webhook subscriptions and the 30 most recent delivery records for the workspace. recent_deliveries are delivery-attempt rows (status, attempt_count, last_error), not the outbound POST payload. Operator routes require a browser session. Workspace admin at /app/admin can create subscriptions, send a test, list attempts, and retry.

Auth

Web Session
Responses
200

Webhook subscriptions
Response Body
Field Type Required Description
recent_deliveries array<object> Yes Hard-capped list of the 30 most recent delivery records
recent_deliveries[].id string Yes Webhook delivery UUID
recent_deliveries[].status string (pending, succeeded, failed) Yes Delivery status
recent_deliveries[].inserted_at datetime (ISO 8601) Yes Record insertion timestamp
recent_deliveries[].attempt_count integer Yes Number of delivery attempts
recent_deliveries[].event_type string Yes Event type delivered
recent_deliveries[].delivered_at datetime (ISO 8601) No When delivery succeeded
recent_deliveries[].last_error string No Most recent delivery error
recent_deliveries[].last_response_code integer No Most recent HTTP response status code
recent_deliveries[].next_attempt_at datetime (ISO 8601) No When the next retry is scheduled
recent_deliveries[].webhook_subscription_id string Yes Webhook subscription UUID
webhook_subscriptions array<object> Yes List of webhook subscriptions
webhook_subscriptions[].enabled boolean Yes Whether the subscription is enabled
webhook_subscriptions[].id string Yes Webhook subscription UUID
webhook_subscriptions[].name string Yes Webhook subscription name
webhook_subscriptions[].url string Yes Webhook destination URL
webhook_subscriptions[].headers object Yes Additional headers sent with deliveries
webhook_subscriptions[].inserted_at datetime (ISO 8601) Yes Record insertion timestamp
webhook_subscriptions[].updated_at datetime (ISO 8601) Yes Record update timestamp
webhook_subscriptions[].event_types array<string> Yes Subscribed event types
webhook_subscriptions[].last_triggered_at datetime (ISO 8601) No Most recent successful trigger timestamp
Example
{
  "recent_deliveries": [
    {
      "attempt_count": 1,
      "delivered_at": "2026-03-12T09:05:03Z",
      "event_type": "trace.finalized",
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "inserted_at": "2026-03-12T09:05:02Z",
      "last_error": null,
      "last_response_code": 200,
      "next_attempt_at": null,
      "status": "succeeded",
      "webhook_subscription_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "webhook_subscriptions": [
    {
      "enabled": true,
      "event_types": [
        "trace.finalized",
        "command.complete",
        "command.fail"
      ],
      "headers": {},
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "inserted_at": "2026-03-10T14:00:00Z",
      "last_triggered_at": "2026-03-12T09:05:03Z",
      "name": "Production alerts",
      "updated_at": "2026-03-12T09:05:03Z",
      "url": "https://example.com/webhooks/agentops"
    }
  ]
}
401

An authenticated operator session is required
POST
/api/v1/operator/webhook_subscriptions Web Session

Create webhook subscription

Description

Registers a webhook destination and event subscriptions. Omitting event_types creates a wildcard subscription (["*"]). Create never returns signing_secret — only POST .../rotate_secret adds the secret to the JSON.

Auth

Web Session
Request Body
Field Type Required Description
webhook_subscription object Yes Webhook subscription attributes
webhook_subscription.enabled boolean No Whether the subscription is enabled
webhook_subscription.name string Yes Webhook subscription name
webhook_subscription.url string Yes Webhook destination URL
webhook_subscription.headers object No Additional headers to send with webhook deliveries
webhook_subscription.event_types array<string> No Event types to subscribe to. Omitted values default to ["*"] before validation.
webhook_subscription.signing_secret string No Optional signing secret used for webhook verification; generated automatically when omitted. Never echoed on create.
Responses
201

Webhook subscription created (no signing_secret)
Response Body
Field Type Required Description
enabled boolean Yes Whether the subscription is enabled
id string Yes Webhook subscription UUID
name string Yes Webhook subscription name
url string Yes Webhook destination URL
headers object Yes Additional headers sent with deliveries
inserted_at datetime (ISO 8601) Yes Record insertion timestamp
updated_at datetime (ISO 8601) Yes Record update timestamp
event_types array<string> Yes Subscribed event types
last_triggered_at datetime (ISO 8601) No Most recent successful trigger timestamp
Example
{
  "enabled": true,
  "event_types": [
    "trace.finalized",
    "command.complete",
    "command.fail"
  ],
  "headers": {},
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "inserted_at": "2026-03-10T14:00:00Z",
  "last_triggered_at": "2026-03-12T09:05:03Z",
  "name": "Production alerts",
  "updated_at": "2026-03-12T09:05:03Z",
  "url": "https://example.com/webhooks/agentops"
}
401

An authenticated operator session is required
422

Validation failed
PATCH
/api/v1/operator/webhook_subscriptions/:id Web Session

Update webhook subscription

Description

Updates destination, secret behavior, or subscribed events.

Auth

Web Session
Request Body
Field Type Required Description
webhook_subscription object Yes Webhook subscription attributes to update
webhook_subscription.enabled boolean No Whether the subscription is enabled
webhook_subscription.name string No Webhook subscription name
webhook_subscription.url string No Webhook destination URL
webhook_subscription.headers object No Additional headers to send with webhook deliveries
webhook_subscription.event_types array<string> No Array of event types to subscribe to
webhook_subscription.signing_secret string No Replace the signing secret used for webhook verification
Parameters
Name In Type Required Description
id path string Yes Webhook subscription UUID
Responses
200

Webhook subscription updated
Response Body
Field Type Required Description
enabled boolean Yes Whether the subscription is enabled
id string Yes Webhook subscription UUID
name string Yes Webhook subscription name
url string Yes Webhook destination URL
headers object Yes Additional headers sent with deliveries
inserted_at datetime (ISO 8601) Yes Record insertion timestamp
updated_at datetime (ISO 8601) Yes Record update timestamp
event_types array<string> Yes Subscribed event types
last_triggered_at datetime (ISO 8601) No Most recent successful trigger timestamp
Example
{
  "enabled": true,
  "event_types": [
    "trace.finalized",
    "command.complete",
    "command.fail"
  ],
  "headers": {},
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "inserted_at": "2026-03-10T14:00:00Z",
  "last_triggered_at": "2026-03-12T09:05:03Z",
  "name": "Production alerts",
  "updated_at": "2026-03-12T09:05:03Z",
  "url": "https://example.com/webhooks/agentops"
}
401

An authenticated operator session is required
404

Webhook subscription not found
DELETE
/api/v1/operator/webhook_subscriptions/:id Web Session

Delete webhook subscription

Description

Deletes a webhook subscription.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Webhook subscription UUID
Responses
204

Webhook subscription deleted
401

An authenticated operator session is required
404

Webhook subscription not found
POST
/api/v1/operator/webhook_subscriptions/:id/rotate_secret Web Session

Rotate webhook signing secret

Description

Generates and returns a new webhook signing secret. This is the only operator action that includes signing_secret in the JSON.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Webhook subscription UUID
Responses
200

Signing secret rotated
Response Body
Field Type Required Description
enabled boolean Yes Whether the subscription is enabled
id string Yes Webhook subscription UUID
name string Yes Webhook subscription name
url string Yes Webhook destination URL
headers object Yes Additional headers sent with deliveries
inserted_at datetime (ISO 8601) Yes Record insertion timestamp
updated_at datetime (ISO 8601) Yes Record update timestamp
event_types array<string> Yes Subscribed event types
last_triggered_at datetime (ISO 8601) No Most recent successful trigger timestamp
signing_secret string Yes One-time rotated signing secret
Example
{
  "enabled": true,
  "event_types": [
    "trace.finalized",
    "command.complete",
    "command.fail"
  ],
  "headers": {},
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "inserted_at": "2026-03-10T14:00:00Z",
  "last_triggered_at": "2026-03-12T09:05:03Z",
  "name": "Production alerts",
  "signing_secret": "dGhpcyBpcyBhIHRlc3Qgc2VjcmV0",
  "updated_at": "2026-03-12T09:05:03Z",
  "url": "https://example.com/webhooks/agentops"
}
401

An authenticated operator session is required
404

Webhook subscription not found
POST
/api/v1/operator/webhook_subscriptions/:id/test Web Session

Send a test webhook delivery

Description

Enqueues a signed sample event (event_type webhook.test, payload.test true) and returns the delivery record as 202.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Webhook subscription UUID
Responses
202

Test delivery enqueued
Response Body
Field Type Required Description
id string Yes Webhook delivery UUID
status string (pending, succeeded, failed) Yes Delivery status
inserted_at datetime (ISO 8601) Yes Record insertion timestamp
attempt_count integer Yes Number of delivery attempts
event_type string Yes Event type delivered
delivered_at datetime (ISO 8601) No When delivery succeeded
last_error string No Most recent delivery error
last_response_code integer No Most recent HTTP response status code
next_attempt_at datetime (ISO 8601) No When the next retry is scheduled
webhook_subscription_id string Yes Webhook subscription UUID
Example
{
  "attempt_count": 1,
  "delivered_at": null,
  "event_type": "webhook.test",
  "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "inserted_at": "2026-03-12T09:05:02Z",
  "last_error": null,
  "last_response_code": null,
  "next_attempt_at": null,
  "status": "pending",
  "test": true,
  "webhook_subscription_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}
401

An authenticated operator session is required
404

Webhook subscription not found
GET
/api/v1/operator/webhook_subscriptions/:id/deliveries Web Session

List recent webhook deliveries

Description

Returns recent delivery-attempt records for the subscription. limit defaults to 30 and is capped at 100.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Webhook subscription UUID
limit query integer No Page size (default 30, maximum 100)
Responses
200

Recent deliveries
Example
{
  "deliveries": [
    {
      "attempt_count": 1,
      "delivered_at": "2026-03-12T09:05:03Z",
      "event_type": "trace.finalized",
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "inserted_at": "2026-03-12T09:05:02Z",
      "last_error": null,
      "last_response_code": 200,
      "next_attempt_at": null,
      "status": "succeeded",
      "webhook_subscription_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ]
}
401

An authenticated operator session is required
404

Webhook subscription not found
POST
/api/v1/operator/webhook_deliveries/:id/redeliver Web Session

Redeliver a webhook delivery

Description

Resets the delivery's attempt_count and re-enqueues it. Returns 202 with the delivery record.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Webhook delivery UUID
Responses
202

Delivery re-enqueued
Response Body
Field Type Required Description
id string Yes Webhook delivery UUID
status string (pending, succeeded, failed) Yes Delivery status
inserted_at datetime (ISO 8601) Yes Record insertion timestamp
attempt_count integer Yes Number of delivery attempts
event_type string Yes Event type delivered
delivered_at datetime (ISO 8601) No When delivery succeeded
last_error string No Most recent delivery error
last_response_code integer No Most recent HTTP response status code
next_attempt_at datetime (ISO 8601) No When the next retry is scheduled
webhook_subscription_id string Yes Webhook subscription UUID
Example
{
  "attempt_count": 1,
  "delivered_at": "2026-03-12T09:05:03Z",
  "event_type": "trace.finalized",
  "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "inserted_at": "2026-03-12T09:05:02Z",
  "last_error": null,
  "last_response_code": 200,
  "next_attempt_at": null,
  "status": "succeeded",
  "webhook_subscription_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}
401

An authenticated operator session is required
404

Webhook delivery not found