API Reference

Webhook endpoints can be managed from Settings, Webhooks, or with these endpoints. GET requests need the read:webhooks scope; everything else needs write:webhooks (or * for full access).

Endpoint	Method	Scope	What it does
`/api/v1/webhooks`	GET	`read:webhooks`	List endpoints
`/api/v1/webhooks`	POST	`write:webhooks`	Add an endpoint. The response has the signing secret, shown once
`/api/v1/webhooks/events`	GET	`read:webhooks`	List event names
`/api/v1/webhooks/{id}`	GET	`read:webhooks`	Get one endpoint
`/api/v1/webhooks/{id}`	PATCH	`write:webhooks`	Change `url`, `events`, `description` or `active`
`/api/v1/webhooks/{id}`	DELETE	`write:webhooks`	Delete an endpoint and its history
`/api/v1/webhooks/{id}/rotate-secret`	POST	`write:webhooks`	Issue a new secret. The old one stops working at once
`/api/v1/webhooks/{id}/test`	POST	`write:webhooks`	Send a `webhook.test` event now and return the result
`/api/v1/webhooks/{id}/deliveries`	GET	`read:webhooks`	Recent deliveries, with the payload sent
`/api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver`	POST	`write:webhooks`	Send that event again now

Errors use the usual shape, { "error": "<message>" }, with a message you can show to a person: 400 for invalid input (for example The webhook URL must start with https://.), 401/403 for the key, and 404 for Webhook endpoint not found. or Webhook delivery not found.

The reference below is generated from the OpenAPI spec. The live playground is disabled to prevent accidental writes to production from the docs site.

GET/api/v1/webhooks

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/webhooks"

{  "webhooks": [    {      "id": "cmq9hook0alk34567890",      "url": "https://hooks.example.com/agentlyleads",      "description": "Mirror new leads into billing",      "events": [        "lead.created",        "deal.stage_changed"      ],      "active": true,      "consecutiveFailures": 0,      "disabledAt": null,      "disabledReason": null,      "createdAt": "2026-09-27T14:00:00.000Z",      "updatedAt": "2026-09-27T14:00:00.000Z"    }  ]}

{  "error": "products must not be empty."}

{  "error": "products must not be empty."}

POST/api/v1/webhooks

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

url*string

Public https URL. Private, loopback and link-local hosts are refused.

Formaturi

events*array<>

Items1 <= items

description?|

Lengthlength <= 200

active?boolean

Defaulttrue

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "https://hooks.example.com/agentlyleads",    "events": [      "lead.created",      "deal.stage_changed"    ],    "description": "Mirror new leads into billing"  }'

{  "webhook": {    "id": "cmq9hook0alk34567890",    "url": "https://hooks.example.com/agentlyleads",    "description": "Mirror new leads into billing",    "events": [      "lead.created",      "deal.stage_changed"    ],    "active": true,    "consecutiveFailures": 0,    "disabledAt": null,    "disabledReason": null,    "createdAt": "2026-09-27T14:00:00.000Z",    "updatedAt": "2026-09-27T14:00:00.000Z"  },  "secret": "whsec_3q2-8Hc0yGm1f5o4k0B7Qx9ZtP1vLr6sWd2eNa8uJcI"}

{  "error": "products must not be empty."}

{  "error": "products must not be empty."}

{  "error": "products must not be empty."}

GET/api/v1/webhooks/events

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/webhooks/events"

{  "events": [    {      "type": "contact.created",      "description": "A contact was added, by hand, import, API, sync or MCP."    }  ]}

{  "error": "products must not be empty."}

GET/api/v1/webhooks/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The endpoint ID.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/webhooks/string"

{  "webhook": {    "id": "string",    "url": "string",    "description": "string",    "events": [      "string"    ],    "active": true,    "consecutiveFailures": 0,    "disabledAt": "2019-08-24T14:15:22Z",    "disabledReason": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

{  "error": "products must not be empty."}

PATCH/api/v1/webhooks/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The endpoint ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Properties1 <= properties

url?string

Formaturi

events?array<string>

Items1 <= items

description?|

Lengthlength <= 200

active?boolean

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/webhooks/string" \  -H "Content-Type: application/json" \  -d '{    "active": true  }'

{  "webhook": {    "id": "string",    "url": "string",    "description": "string",    "events": [      "string"    ],    "active": true,    "consecutiveFailures": 0,    "disabledAt": "2019-08-24T14:15:22Z",    "disabledReason": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

{  "error": "products must not be empty."}

{  "error": "products must not be empty."}

DELETE/api/v1/webhooks/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The endpoint ID.

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/webhooks/string"

{  "deleted": 1,  "id": "string"}

{  "error": "products must not be empty."}

POST/api/v1/webhooks/{id}/rotate-secret

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/webhooks/string/rotate-secret"

{  "webhook": {    "id": "string",    "url": "string",    "description": "string",    "events": [      "string"    ],    "active": true,    "consecutiveFailures": 0,    "disabledAt": "2019-08-24T14:15:22Z",    "disabledReason": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "secret": "string"}

{  "error": "products must not be empty."}

POST/api/v1/webhooks/{id}/test

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/webhooks/string/test"

{  "delivery": {    "id": "cmq9dlvr0alk34567890",    "endpointId": "cmq9hook0alk34567890",    "eventId": "evt_5b1f0c7d2a9e4f6b8c3d1e0a",    "type": "webhook.test",    "eventCreatedAt": "2026-09-27T14:05:00.000Z",    "status": "SUCCEEDED",    "attempts": 1,    "nextAttemptAt": null,    "lastAttemptAt": "2026-09-27T14:05:00.000Z",    "responseStatus": 200,    "durationMs": 184,    "lastError": null,    "deliveredAt": "2026-09-27T14:05:00.000Z",    "createdAt": "2026-09-27T14:05:00.000Z"  }}

{  "error": "products must not be empty."}

GET/api/v1/webhooks/{id}/deliveries

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

Query Parameters

status?string

Value in

"PENDING"
"SUCCEEDED"
"FAILED"

limit?integer

Range1 <= value <= 100

Default50

cursor?string

The nextCursor from the previous page.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/webhooks/string/deliveries"

{  "deliveries": [    {      "id": "string",      "endpointId": "string",      "eventId": "string",      "type": "string",      "eventCreatedAt": "2019-08-24T14:15:22Z",      "status": "PENDING",      "attempts": 0,      "nextAttemptAt": "2019-08-24T14:15:22Z",      "lastAttemptAt": "2019-08-24T14:15:22Z",      "responseStatus": 0,      "durationMs": 0,      "lastError": "string",      "deliveredAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z",      "data": {}    }  ],  "nextCursor": "string"}

{  "error": "products must not be empty."}

{  "error": "products must not be empty."}

POST/api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

deliveryId*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/webhooks/string/deliveries/string/redeliver"

{  "delivery": {    "id": "string",    "endpointId": "string",    "eventId": "string",    "type": "string",    "eventCreatedAt": "2019-08-24T14:15:22Z",    "status": "PENDING",    "attempts": 0,    "nextAttemptAt": "2019-08-24T14:15:22Z",    "lastAttemptAt": "2019-08-24T14:15:22Z",    "responseStatus": 0,    "durationMs": 0,    "lastError": "string",    "deliveredAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z"  }}

{  "error": "products must not be empty."}

API Reference

200application/json

401application/json

403application/json

201application/json

400application/json

401application/json

403application/json

200application/json

401application/json

200application/json

404application/json

200application/json

400application/json

404application/json

200application/json

404application/json

200application/json

404application/json

200application/json

404application/json

200application/json

400application/json

404application/json

200application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`