Webhooks
Webhooks, the events they send and their deliveries.
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-500). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].adAccountIds- 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[].createdAt- Created.
items[].createdBy- The person accountable: the creator, or the person an agent acts for.
items[].createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. items[].delivering- List only: whether events go out to it now.
items[].events- Events.
items[].id- Webhook.
items[].lastDelivery- List only: the latest delivery's
status,responseStatusandcreatedAt; null before the first. items[].notDelivering- List only: why it doesn't deliver now; null while it does.
reason(role,no_access,credential_endedornobody),userIdanduserName, the person accountable for it, andmessage, one sentence to show. items[].secret- Only in the create and rotate-secret responses.
items[].updatedAt- Last changed (URL, events or secret).
items[].url- Endpoint.
items[].version- Pass as
expectedVersionwhen changing it. nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/webhooks" \
-H "Authorization: Bearer $PLUTO_KEY"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).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
events- Events to deliver.
url- HTTPS endpoint.
Response
adAccountIds- The ad accounts whose events it delivers; null: every event. A webhook made by a credential limited to some ad accounts delivers only theirs.
createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. delivering- List only: whether events go out to it now.
events- Events.
id- Webhook.
lastDelivery- List only: the latest delivery's
status,responseStatusandcreatedAt; null before the first. notDelivering- List only: why it doesn't deliver now; null while it does.
reason(role,no_access,credential_endedornobody),userIdanduserName, the person accountable for it, andmessage, one sentence to show. secret- Only in the create and rotate-secret responses.
updatedAt- Last changed (URL, events or secret).
url- Endpoint.
version- Pass as
expectedVersionwhen 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'List webhook events
Events a webhook can subscribe to.
Creating a webhook with another event name is a 422. * subscribes to everything.
Response
[].description- When it fires.
[].name- Event.
Errors
- 400The request is malformed.
curl "$PLUTO_API/webhooks/events"Change a webhook
Changes the URL and/or events; the signing secret stays. A stale expectedVersion is a 409 carrying current.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The webhook's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
events- Events to deliver (replaces the list).
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
url- HTTPS endpoint.
Response
adAccountIds- The ad accounts whose events it delivers; null: every event. A webhook made by a credential limited to some ad accounts delivers only theirs.
createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. delivering- List only: whether events go out to it now.
events- Events.
id- Webhook.
lastDelivery- List only: the latest delivery's
status,responseStatusandcreatedAt; null before the first. notDelivering- List only: why it doesn't deliver now; null while it does.
reason(role,no_access,credential_endedornobody),userIdanduserName, the person accountable for it, andmessage, one sentence to show. secret- Only in the create and rotate-secret responses.
updatedAt- Last changed (URL, events or secret).
url- Endpoint.
version- Pass as
expectedVersionwhen 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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 a webhook
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The webhook's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"List recent deliveries
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The webhook's ID. |
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-500). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].attempts- Attempts.
items[].createdAt- Created.
items[].deliveredAt- Delivered.
items[].event- Event type.
items[].eventId- The event.
items[].id- Delivery.
items[].lastError- Error.
items[].nextAttemptAt- Next attempt.
items[].responseStatus- Your endpoint's HTTP status.
items[].status- Outcome.One of
pending,delivered,failed nextAfter- 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-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The webhook's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountIds- The ad accounts whose events it delivers; null: every event. A webhook made by a credential limited to some ad accounts delivers only theirs.
createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. delivering- List only: whether events go out to it now.
events- Events.
id- Webhook.
lastDelivery- List only: the latest delivery's
status,responseStatusandcreatedAt; null before the first. notDelivering- List only: why it doesn't deliver now; null while it does.
reason(role,no_access,credential_endedornobody),userIdanduserName, the person accountable for it, andmessage, one sentence to show. secret- Only in the create and rotate-secret responses.
updatedAt- Last changed (URL, events or secret).
url- Endpoint.
version- Pass as
expectedVersionwhen 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"Send a test event
Queues one signed webhook.test event to this endpoint only. The outcome shows in its deliveries and in the job.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The webhook's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
deliveryId- The test delivery.
eventwebhook.test.jobId- The delivery job.
webhookId- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"