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.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.
npm install standardwebhooks or pip install standardwebhooks.
Respond quickly
Pipecat Cloud treats any2xx 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. Thesvix-id header is stable across every retry of the same message, which makes it the right deduplication key:
- Events produced by periodic jobs (
org.trial_endedand thespend.*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 awebhook-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.
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.