API reference
Webhooks
Register endpoints that receive project events.
Create a webhook
POST
/projects/{project}/webhooksRegisters an HTTPS endpoint. The response includes the signing secret — it is shown only once.
Headers
AuthorizationstringrequiredBearer <token>
Path parameters
projectstringrequired- Project id, e.g.
prj_8d2kq.
Body parameters
urlstringrequired- HTTPS URL that receives POST requests.
eventsstring[]required- e.g.
flag.updated,rollout.step. environmentsstring[]optional- Limit to these environments. Default: all.
Request
Terminal
curl -X POST https://api.shoal.dev/v2/projects/prj_8d2kq/webhooks \
-H "Authorization: Bearer $SHOAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "url": "https://acme.dev/hooks/shoal", "events": ["flag.updated"] }'TypeScript
const hook = await api.webhooks.create("prj_8d2kq", {
url: "https://acme.dev/hooks/shoal",
events: ["flag.updated"],
});Python
hook = api.webhooks.create("prj_8d2kq", url="https://acme.dev/hooks/shoal", events=["flag.updated"])Response
JSON
{
"id": "wh_3kd92",
"url": "https://acme.dev/hooks/shoal",
"events": ["flag.updated"],
"secret": "whsec_5f1c…"
}Delete a webhook
DELETE
/projects/{project}/webhooks/{id}Stops deliveries immediately.
Headers
AuthorizationstringrequiredBearer <token>
Path parameters
projectstringrequired- Project id, e.g.
prj_8d2kq. idstringrequired- Webhook id.
Request
Terminal
curl -X DELETE https://api.shoal.dev/v2/projects/prj_8d2kq/webhooks/wh_3kd92 \
-H "Authorization: Bearer $SHOAL_TOKEN"TypeScript
await api.webhooks.delete("prj_8d2kq", "wh_3kd92");Python
api.webhooks.delete("prj_8d2kq", "wh_3kd92")Response
— No Content —