Skip to main content
POST
Create a webhook subscription

Authorizations

Authorization
string
header
required

API key created in the Agentova app (Settings → API), sent as Authorization: Bearer agk_live_…. One key = one workspace: the key determines the workspace, and no workspace identifier ever travels in requests. The Bearer scheme is case-insensitive. A revoked key is refused immediately.

Body

application/json
url
string<uri>
required

URL that receives the deliveries. HTTPS is required; no private or local address; no credentials in the URL.

events
enum<string>[]
required

Event types to receive (at least one).

Minimum array length: 1
  • lead.created: a lead was created (data is a Lead).
  • run.completed: an automation completed a run (data is a Run).
  • automation.status_changed: the status of an automation changed (data is an Automation).
Available options:
run.completed,
lead.created,
automation.status_changed

Callbacks

POST
{$request.body#/url}delivery

Body

application/json

Body sent to the subscribed URL. type (a WebhookEvent value) determines the shape of data: a Lead for lead.created, a Run for run.completed, an Automation for automation.status_changed.

id
string
required

Opaque identifier prefixed with evt_, unique per event: use it to deduplicate. It is the same on every delivery attempt and for every subscription that receives the event.

created_at
string<date-time>
required

When the event was generated.

type
enum<string>
required
Available options:
lead.created
data
object
required

A contact captured by one of the workspace's agents.

Response

Unsubscribe: the subscription is deleted immediately, without notification, and nothing is retried.

Response

Subscription created. The secret is returned only in this response.

A webhook subscription. It belongs to the workspace. Revoking the API key that created it deletes it as well, unless the admin unticks that option in Settings → API.

id
string
required

Opaque identifier prefixed with whk_.

url
string<uri>
required

URL that receives the deliveries.

events
enum<string>[]
required

Event types sent to this URL.

  • lead.created: a lead was created (data is a Lead).
  • run.completed: an automation completed a run (data is a Run).
  • automation.status_changed: the status of an automation changed (data is an Automation).
Available options:
run.completed,
lead.created,
automation.status_changed
created_at
string<date-time>
required

When the subscription was created.

disabled_at
string<date-time> | null
required

Set when Agentova disabled the subscription, typically after prolonged delivery failures (see POST /webhooks); null otherwise. A disabled subscription receives nothing and cannot be re-enabled: delete it and create a new one. It is deleted automatically 30 days after this date.

secret
string
required

Signing secret (whsec_…), shown only once. The complete string, prefix included, is the HMAC key used to sign the deliveries.