API reference

Webhooks

Webhooks, the events they send and their deliveries.

GET/webhooks

List webhooks

Each with its latest delivery and whether it delivers now. A webhook delivers only while the person accountable for it may manage webhooks in this workspace: its creator, or for one an API key or agent created, that credential's person while the credential works. It starts again by itself when they may again; events in between aren't sent later.

Permission: admin

Parameters

NameTypeRequiredDescription
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].adAccountIdsarray of strings or null
The ad accounts whose events it delivers; null: every event. A webhook made by a credential limited to some ad accounts delivers only theirs.
items[].createdAtstring (date-time)
Created.
items[].createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
items[].createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
items[].deliveringboolean
List only: whether events go out to it now.
items[].eventsarray of strings
Events.
items[].idstring (uuid)Required
Webhook.
items[].lastDeliveryobject
List only: the latest delivery's status, responseStatus and createdAt; null before the first.
items[].notDeliveringobject or null
List only: why it doesn't deliver now; null while it does. reason (role, no_access, credential_ended or nobody), userId and userName, the person accountable for it, and message, one sentence to show.
items[].secretstring or null
Only in the create and rotate-secret responses.
items[].updatedAtstring (date-time)
Last changed (URL, events or secret).
items[].urlstringRequired
Endpoint.
items[].versioninteger
Pass as expectedVersion when changing it.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/webhooks" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/webhooks

Create a webhook

Deliveries are signed; the signing secret is in this response only. 403 while the organization lets only its owners and admins create webhooks (credentialPolicy.membersMayCreateWebhooks).

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

eventsarray of stringsRequired
Events to deliver.
urlstringRequired
HTTPS endpoint.

Response201 Created

adAccountIdsarray of strings or null
The ad accounts whose events it delivers; null: every event. A webhook made by a credential limited to some ad accounts delivers only theirs.
createdAtstring (date-time)
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
deliveringboolean
List only: whether events go out to it now.
eventsarray of strings
Events.
idstring (uuid)Required
Webhook.
lastDeliveryobject
List only: the latest delivery's status, responseStatus and createdAt; null before the first.
notDeliveringobject or null
List only: why it doesn't deliver now; null while it does. reason (role, no_access, credential_ended or nobody), userId and userName, the person accountable for it, and message, one sentence to show.
secretstring or null
Only in the create and rotate-secret responses.
updatedAtstring (date-time)
Last changed (URL, events or secret).
urlstringRequired
Endpoint.
versioninteger
Pass as expectedVersion when changing it.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/webhooks" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 87d95ead-a452-4835-917f-e8f0c2c3bbfa" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "Brevanne"
    ],
    "url": "https://brevanne.com/products/vitamin-c-serum"
  }'
GET/webhooks/events

List webhook events

Events a webhook can subscribe to.

Creating a webhook with another event name is a 422. * subscribes to everything.

No credential

Response200 OK

[].descriptionstringRequired
When it fires.
[].namestringRequired
Event.

Errors

  • 400The request is malformed.
curl "$PLUTO_API/webhooks/events"
PATCH/webhooks/{id}

Change a webhook

Changes the URL and/or events; the signing secret stays. A stale expectedVersion is a 409 carrying current.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe webhook's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

eventsarray of strings
Events to deliver (replaces the list).
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
urlstring
HTTPS endpoint.

Response200 OK

adAccountIdsarray of strings or null
The ad accounts whose events it delivers; null: every event. A webhook made by a credential limited to some ad accounts delivers only theirs.
createdAtstring (date-time)
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
deliveringboolean
List only: whether events go out to it now.
eventsarray of strings
Events.
idstring (uuid)Required
Webhook.
lastDeliveryobject
List only: the latest delivery's status, responseStatus and createdAt; null before the first.
notDeliveringobject or null
List only: why it doesn't deliver now; null while it does. reason (role, no_access, credential_ended or nobody), userId and userName, the person accountable for it, and message, one sentence to show.
secretstring or null
Only in the create and rotate-secret responses.
updatedAtstring (date-time)
Last changed (URL, events or secret).
urlstringRequired
Endpoint.
versioninteger
Pass as expectedVersion when changing it.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/webhooks/81d942b7-2b51-400c-a88c-314677031433" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: d43ca0fa-7023-4bb3-9ab1-45a9963ae9ca" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "Brevanne"
    ],
    "expectedVersion": 3,
    "url": "https://brevanne.com/products/vitamin-c-serum"
  }'
DELETE/webhooks/{id}

Delete a webhook

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe webhook's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

Done; no content.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/webhooks/81d942b7-2b51-400c-a88c-314677031433" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 9a7b892f-26a6-467a-9018-07f23eae921e"
GET/webhooks/{id}/deliveries

List recent deliveries

Permission: admin

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe webhook's ID.
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].attemptsintegerRequired
Attempts.
items[].createdAtstring (date-time)
Created.
items[].deliveredAtstring (date-time) or null
Delivered.
items[].eventstringRequired
Event type.
items[].eventIdstring (uuid) or null
The event.
items[].idstring (uuid)Required
Delivery.
items[].lastErrorstring or null
Error.
items[].nextAttemptAtstring (date-time)
Next attempt.
items[].responseStatusinteger or null
Your endpoint's HTTP status.
items[].statusstringRequired
Outcome.One of pending, delivered, failed
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/webhooks/81d942b7-2b51-400c-a88c-314677031433/deliveries" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/webhooks/{id}/rotate-secret

Rotate a webhook's signing secret

Replaces the signing secret at once: every delivery from now on, retries included, is signed with the new one. The new secret is in this response only; a replay returns the webhook without it.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe webhook's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdsarray of strings or null
The ad accounts whose events it delivers; null: every event. A webhook made by a credential limited to some ad accounts delivers only theirs.
createdAtstring (date-time)
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
deliveringboolean
List only: whether events go out to it now.
eventsarray of strings
Events.
idstring (uuid)Required
Webhook.
lastDeliveryobject
List only: the latest delivery's status, responseStatus and createdAt; null before the first.
notDeliveringobject or null
List only: why it doesn't deliver now; null while it does. reason (role, no_access, credential_ended or nobody), userId and userName, the person accountable for it, and message, one sentence to show.
secretstring or null
Only in the create and rotate-secret responses.
updatedAtstring (date-time)
Last changed (URL, events or secret).
urlstringRequired
Endpoint.
versioninteger
Pass as expectedVersion when changing it.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/webhooks/81d942b7-2b51-400c-a88c-314677031433/rotate-secret" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: c09ced5e-9df9-4e14-93f1-6ee224a6e4dc"
POST/webhooks/{id}/test

Send a test event

Queues one signed webhook.test event to this endpoint only. The outcome shows in its deliveries and in the job.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe webhook's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response202 Accepted

deliveryIdstring (uuid)Required
The test delivery.
eventstringRequired
webhook.test.
jobIdstring (uuid)Required
The delivery job.
webhookIdstring (uuid)Required
Webhook.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/webhooks/81d942b7-2b51-400c-a88c-314677031433/test" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 3b53585e-5151-4e1d-99f2-b871ca68b3f2"