FlowModels

Create webhooks via API, test them and change the secret

Published on 11. November 2026

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_scope here.

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 reachable https address, 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.test
  • description: 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 delivery
  • delivered: your server responded with 2xx
  • failed: the last attempt failed, another will follow
  • exhausted: 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.deactivated event 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 id of an address as webhook_endpoint_id at the start, see Long requests in the background.

Was this article helpful?

Back to Webhooks, end users & MCP