You normally set up webhook addresses in the interface, see Set up FlowModels webhooks. If you set up many environments automatically, your deployment can also do this itself through the API. Here are the endpoints and which key you need for what.
Which key?
- Creating, listing, changing, deleting, testing and reading the delivery log: a key with Use AI
- Changing the secret: a key with Manage keys. A key with Use AI gets
403 insufficient_key_scopehere.
All paths start with https://api.flowmodels.one/v1.
Create an address
curl -X POST https://api.flowmodels.one/v1/webhook_endpoints \
-H "Authorization: Bearer at_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://portal.example.de/webhooks/flowmodels", "events": ["response.completed", "response.failed", "credit.threshold"], "description": "Customer portal production"}'
url: a publicly reachablehttpsaddress, at most 2,048 characters. We check it when you save and again before each delivery.events: at least one event from this list:response.completed,response.failed,response.cancelled,response.incomplete,credit.threshold,credit.topup_failed,webhook_endpoint.deactivated,webhook.testdescription: optional, at most 255 characters
The response contains the address's id and, in the secret field, the signing secret. The secret appears only in this one response. Store it in your secret manager right away. Verify the webhook signature: sample code for PHP, Node.js and Python explains how to use it to verify deliveries.
At most 10 addresses are possible per team. The eleventh is rejected with HTTP 400.
List, change, delete
| Task | Call |
|---|---|
| all addresses | GET /webhook_endpoints |
| one address | GET /webhook_endpoints/{id} |
| change | PATCH /webhook_endpoints/{id} |
| delete | DELETE /webhook_endpoints/{id} |
The lists are paginated with limit and after. These calls never return a secret.
With PATCH, you change url, events, description and is_active. With "is_active": false, you pause an address, and with true you put it back into operation, for example after we switched it off because of repeated errors.
DELETE removes the address together with its delivery log. We respond to an unknown ID or one belonging to someone else with 404 webhook_endpoint_not_found.
Test and check deliveries
POST /webhook_endpoints/{id}/test queues a delivery of type webhook.test. The response comes immediately with status: "pending", and the actual delivery follows shortly after.
You can see whether it arrived with GET /webhook_endpoints/{id}/deliveries. Each entry states the event_type, status, the number of attempts, your server's http_status, failure_kind and the timestamps. With ?status=, you can filter by:
pending: waiting for deliverydelivered: your server responded with 2xxfailed: the last attempt failed, another will followexhausted: all attempts have failed
Change the secret
curl -X POST https://api.flowmodels.one/v1/webhook_endpoints/{id}/rotate_secret \
-H "Authorization: Bearer at_your_management_key"
The response contains the new secret, again only this one time, and secondary_secret_expires_at. Until that time, so for 24 hours, we sign every delivery with both secrets. The webhook-signature header then contains two values. This lets you roll out the new secret on all servers at your own pace, without losing a delivery.
Good to know
- The
webhook_endpoint.deactivatedevent goes to all other active addresses of your team, never to the one that was just switched off. So it's best to create a second address if you want to be informed about deactivations. - For background jobs, you can pass the
idof an address aswebhook_endpoint_idat the start, see Long requests in the background.