We tell you when something is done.
FlowModels calls your address when a background run ends, a threshold is reached or a target fails. Every delivery is signed, and failed ones are retried.
Five attempts, then it stops.
If your server does not answer within 10 seconds or does not answer with a 2xx status, FlowModels tries again at fixed intervals. Up to 30 seconds of randomness are added to each interval so that not all retries arrive at once.
- Attempt 1 immediately
- Attempt 2 +60 s after about 1 minute
- Attempt 3 +300 s after about 6 minutes
- Attempt 4 +900 s after about 21 minutes
- Attempt 5 +3,600 s after about 81 minutes
After the fifth unsuccessful attempt, the delivery is set to exhausted. If five deliveries fail in a row, FlowModels deactivates the target, tells you by email and sends webhook_endpoint.deactivated to your other targets.
You can see every attempt in the delivery history: GET /v1/webhook_endpoints/{uuid}/deliveries, with the statuses pending, delivered, failed and exhausted.
Eight events.
When you create a target, you pick at least one. Each team can have up to ten targets.
| Event | Triggered when |
|---|---|
response.completed |
A background run has finished |
response.failed |
A background run has failed |
response.cancelled |
A background run was cancelled |
response.incomplete |
A background run ended incomplete |
credit.threshold |
One of your warning thresholds was reached |
credit.topup_failed |
An automatic top-up has failed |
webhook_endpoint.deactivated |
A target was deactivated after repeated failures |
webhook.test |
You triggered the test delivery |
For the four response.* events, the body only holds the ID and the status. You fetch the result with GET /v1/responses/{id}; no content leaves FlowModels through the webhook.
Verify every signature.
The three headers follow the Standard Webhooks scheme. The signature is an HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{Body}, Base64-encoded with the prefix v1,. Use the secret as you received it: as text, not Base64-decoded.
POST /flowmodels/events HTTP/1.1
Host: example.com
Content-Type: application/json
webhook-id: 018f1234-5678-7abc-9def-0123456789ab
webhook-timestamp: 1767225600
webhook-signature: v1,<Base64 of HMAC-SHA256>
{
"id": "018f1234-5678-7abc-9def-0123456789ab",
"type": "response.completed",
"created_at": "2026-11-09T10:15:00+00:00",
"data": {
"id": "018f9abc-1234-7def-8abc-0123456789ab",
"status": "completed"
}
}
import base64, hashlib, hmac, time
def is_valid(body: bytes, headers, secret: str) -> bool:
webhook_id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
# Reject replays: five minutes in either direction.
if abs(time.time() - int(timestamp)) > 300:
return False
signed = f"{webhook_id}.{timestamp}.".encode() + body
digest = hmac.new(secret.encode(), signed, hashlib.sha256).digest()
expected = "v1," + base64.b64encode(digest).decode()
# During a rotation the header carries two signatures.
return any(hmac.compare_digest(expected, candidate)
for candidate in headers["webhook-signature"].split(" "))
Create and test a target.
The secret is only in the response to the creation. POST /v1/webhook_endpoints/{uuid}/test queues a real test delivery and answers with 202.
curl https://api.flowmodels.one/v1/webhook_endpoints \
-H "Authorization: Bearer $FLOWMODELS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/flowmodels/events",
"events": ["response.completed", "credit.threshold"],
"description": "Production"
}'
Rotate the secret without downtime.
POST /v1/webhook_endpoints/{uuid}/rotate_secret returns a new secret, once and only with a management key. For 24 hours, FlowModels signs with the old and the new secret, and the header then holds two values. That way you switch over without losing a delivery.
Public HTTPS targets only.
The address must start with https:// and be at most 2,048 characters long. A target must not point to an internal network: FlowModels checks this on saving and again before every attempt, connects only to the verified address and does not follow redirects.