How do I trigger and react to playbooks with webhooks?
TL;DR: A Webhook trigger gives a playbook a unique HTTP endpoint. External systems POST to that URL to start a run, and the request body is available to the playbook's steps as input. Use webhooks to start playbooks from services that emit outbound events, and use the runs stream to react when a run finishes.
Who this is for
Developers connecting Ballet to systems that emit outbound webhooks (helpdesks, CRMs, CI, payment processors).
How do I trigger a playbook from an external event?
- Open the playbook and add a Webhook trigger in the Trigger panel.
- Copy the generated endpoint URL.
- Register that URL as an outbound webhook in your external system.
- When the system fires the event, it POSTs to the URL and starts a run; the payload is passed to the playbook as input.
curl https://app.ballet.dev/api/webhooks/<your-webhook-path> \
-H "Content-Type: application/json" \
-d '{ "ticketId": "123", "subject": "Refund request" }'
Configure the exact endpoint from the playbook's Trigger panel — it is unique per playbook.
How is this different from the REST execute endpoint?
For your own backend or CI, prefer the authenticated REST execute endpoint.
How do I react when a run finishes?
Subscribe to GET /api/playbooks/:id/runs/stream and watch for the run_stop event, which carries success and output. This lets an external observer act on completion without being the caller that started the run. See Stream run events.
Tips
- Test with a manual trigger and a sample payload before enabling the live webhook.
- Validate and normalize the incoming payload in an early Code step — external systems vary.
- Keep secrets (for callbacks to the source system) in Secrets, not in the playbook body.