Skip to main content
Webhooks let Pipecat Cloud notify your own services when something happens in your organization: a build finishes, a deployment replaces your pods, spend crosses a threshold, a session starts. Instead of polling the REST API, you register an endpoint URL and Pipecat Cloud POSTs a signed JSON payload to it. Every delivery is signed, so your handler can prove the request came from Pipecat Cloud and not from anyone who happened to guess your URL.
Webhook endpoints are managed per organization from the dashboard. There is no CLI command or API-key-authenticated REST route for endpoint management.

Register an endpoint

1

Open the webhooks settings

Go to the Pipecat Cloud dashboard and select Settings > Webhooks for your organization.
2

Add an endpoint

Click Add endpoint and enter the URL that should receive events. Only http and https URLs are accepted; use https for anything reachable from the internet.
3

Choose the events to receive

Select at least one event type. Pipecat Cloud only delivers the types you subscribe to, so you do not have to filter unwanted traffic in your handler. An endpoint with no event types is rejected: if you want an endpoint to stop receiving everything, disable or delete it instead.See the webhook event reference for the full catalog and payload shapes.
4

Copy the signing secret

Use the key icon on the endpoint’s row to reveal its signing secret. It looks like whsec_.... Store it wherever your handler reads its configuration from, and treat it like any other credential.
Each endpoint row also gives you a delivery history view, an edit action for changing the URL or subscriptions, an enable/disable switch, and a send test event action.
Deleting an endpoint destroys its signing secret and delivery history. To stop deliveries temporarily, disable the endpoint instead. Recreating an endpoint at the same URL issues a new secret, and any handler still using the old one will reject every delivery.

Verify the signature

Your endpoint URL is the only thing standing between the public internet and your handler, so verify every request before you act on it. Pipecat Cloud signs every delivery following the Standard Webhooks specification, so any Standard Webhooks library will verify it for you, including the timestamp check that prevents replay of an old but validly signed payload. Three headers carry the signature: These names carry a prefix from the delivery provider, while Standard Webhooks libraries look for them as webhook-id, webhook-timestamp and webhook-signature. Map the three across before verifying, as both samples below do. Nothing else about the scheme differs. Verification also rejects a payload whose timestamp is more than five minutes away from your server’s clock, so keep the receiving host’s time in sync. Pass the library the raw request body exactly as received. Parsing the JSON and re-serializing it changes the bytes, and the signature will no longer match.
Install the library with npm install standardwebhooks or pip install standardwebhooks.
A handler that skips verification will act on anything anyone POSTs to the URL, including forged spend.limit_reached or service.suspended events. If you cannot verify for some reason, do not let the handler take a consequential action on the payload alone.

Respond quickly

Pipecat Cloud treats any 2xx response as a successful delivery and anything else as a failure to be retried. Acknowledge as soon as the signature checks out and move the real work to a queue or a background task, as both samples above do. A handler that does its work inline turns a slow downstream dependency into a delivery failure and a retry storm.

Handle duplicates

Delivery is at-least-once. A retry after a timeout can arrive even though your handler already processed the message, and some events are produced by periodic jobs that can overlap. The svix-id header is stable across every retry of the same message, which makes it the right deduplication key:
Two details worth knowing:
  • Events produced by periodic jobs (org.trial_ended and the spend.* threshold events) carry an idempotency key, so overlapping runs of the same job deliver once rather than twice.
  • Deployment events are sent after the deploy commits. A process restart in that window can drop the event; the deploy itself is unaffected.

Test your handler

Use the send test event action on an endpoint’s row to deliver a sample of any event type that endpoint subscribes to. The body is generated from the event type’s registered schema, so it is shaped exactly like the real event: you can exercise signature verification and payload parsing without producing a real build or session first. The endpoint has to be enabled to receive a test event. Like a manual retry, the action reports that the event was accepted, not that it was delivered. The outcome appears in the delivery history. Test deliveries carry a webhook-test: true header, which real events do not. If it is useful to route them differently, branch on that rather than on anything in the payload: a test event’s body is a realistic sample, so it names a service and a region that may well exist in your account.

Inspect deliveries

The history icon on an endpoint’s row opens its delivery history, newest first. Each row is one message, with its event type, status, and, when a retry is still scheduled, when the next attempt will happen. Opening a delivery shows the exact payload that was sent and every attempt against it, including:
  • the response status code your server returned,
  • how long the request took,
  • the response body (truncated if large),
  • whether the attempt was scheduled or produced by a manual retry.
You can re-dispatch any delivery from here. A retry is queued rather than made inline, so its outcome shows up as a new attempt in the history rather than in the response to the retry itself.
Delivery history looks back 90 days. A delivery older than that reports as not found rather than as aged out.

Troubleshooting

Next steps

Webhook event reference

Every event type, when it fires, and the exact payload it carries.

Pipecat Cloud REST API

Read build, deployment, and session state directly when you need more than an event carries.