Flow API: webhooks
A webhook is an HTTPS request that Flow sends to your server when something happens in a workspace: an object is created, a field changes, an object moves to another status, an SLA is breached, a process finishes. Instead of polling the API, your server receives events on its own.
General API rules — the base URL, keys, headers and errors — are described in Flow API: basics. In the interface, subscriptions are in the workspace settings, in the "Webhooks" section.
How it works
You create a subscription: a URL, a list of events and, optionally, an object filter. Flow issues a signing secret.
Flow sends each matching event to the URL as a
POSTrequest with a JSON body and an HMAC-SHA256 signature.Your server verifies the signature, stores the event and responds with
2xx.If there is no
2xxresponse, Flow retries delivery on a schedule — up to 8 attempts over roughly 24 hours.
A subscription works with the permissions of its principal: events contain only the fields it can read, and the filter is evaluated with its permissions.
Methods
Method | Request |
|---|---|
List subscriptions |
|
Create a subscription |
|
Update a subscription |
|
Delete a subscription |
|
Delivery log |
|
Rotate the secret |
|
Test delivery |
|
Paths are relative to https://flow.sensever.com/v1. All methods require the integration.manage permission. A subscription on behalf of another principal also requires workspace.manage. A workspace can have up to 100 subscriptions.
Create a subscription
POST /webhook-subscriptions:
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | Recipient URL, up to 2048 characters. Only |
| array | yes | 1–64 event patterns: an exact name ( |
| array or null | no | 1–100 type ids: only events of objects of these types. |
| object or null | no | A condition on the object: |
| uuid or null | no | Whose permissions the subscription uses. Defaults to you |
| boolean | no | Defaults to |
| string or null | no | Your own secret: 24–256 visible ASCII characters. Without it, Flow creates a |
curl -s https://flow.sensever.com/v1/webhook-subscriptions \
-H "Authorization: Bearer $FLOW_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hook-deals-1" \
-d '{
"url": "https://hooks.example.com/flow",
"event_types": ["object.created", "object.status_changed", "custom.*"],
"filter": {"type": "deal", "where": {"field": "amount", "op": "gte", "value": 1000}}
}'201 response:
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b90",
"principal_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b74",
"url": "https://hooks.example.com/flow",
"event_types": ["custom.*", "object.created", "object.status_changed"],
"object_type_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b91"],
"filter": {"type": "deal", "where": {"field": "amount", "op": "gte", "value": 1000}},
"enabled": true,
"consecutive_failures": 0,
"disabled_reason": null,
"created_at": "2026-09-25T09:00:00.000000Z",
"updated_at": "2026-09-25T09:00:00.000000Z",
"secret": "whsec_…"
}The secret is shown once — in the response to creation and to secret rotation. Store it in a secrets manager. Repeating the request with the same Idempotency-Key returns the same body, but with secret: null.
filter also sets object_type_ids — from the filter's type. The filter is evaluated against the object's current state when the event is processed, not against the snapshot in the event: if the object has already changed and no longer matches, the event isn't delivered. The condition language is described in Flow API: query language and search.
Update, disable, delete
PATCH /webhook-subscriptions/{id} changes only the fields you pass: url, event_types, object_type_ids, filter, principal_id, enabled. object_type_ids: null and filter: null remove the restriction; principal_id: null sets you.
{"enabled": false} disables the subscription manually (disabled_reason: "manual"). {"enabled": true} enables it again and resets the failure counter. Events that happened while the subscription was disabled aren't delivered — fetch the missed state through the objects API.
DELETE /webhook-subscriptions/{id} deletes the subscription and its not-yet-sent deliveries and returns the deleted subscription.
GET /webhook-subscriptions returns {"items": […]} — the workspace's subscriptions without secrets, newest first.
Events
Event | When | Key |
|---|---|---|
| An object was created |
|
| Fields changed |
|
| An object was archived or restored |
|
| Transition to another status |
|
| A due date reminder fired | rule, offset, due date field |
| A relation was added or removed |
|
| A transition emitted its own event |
|
| An SLA was breached |
|
| An automation failure or loop |
|
| Process progress |
|
| Approval |
|
| An external event was accepted |
|
| A definition was published |
|
| A field index was built |
|
| A background operation finished |
|
| A subscription was disabled automatically |
|
| Members, teams, roles or permissions changed |
|
The <prefix>.* mask works for the catalog namespaces (object, relation, sla, automation, process, approval, external, schema, lifecycle, constraint, field_index, operation, integration, access) and for custom. An unknown name returns 422 VALIDATION_FAILED with the field code unknown_event_type.
The catalog grows: ignore unknown event types and unknown keys.
Subtasks, checklists, tags, recurrence and time
These features have no separate event types — changes arrive as regular object and relation events:
What happened | Event |
|---|---|
A checklist item was checked, added, renamed or deleted (including via |
|
Tags changed |
|
A task's parent was set or removed |
|
A recurrence created the next task in the series |
|
Recurrence settings (PUT and DELETE /objects/{id}/recurrence), time entries and the timer, as well as personal settings (emails, calendar subscriptions, "By section") don't generate events: read them through the API. These methods are described in "Flow API: subtasks, checklists and recurrence" and "Flow API: time tracking".
What you receive
POST /flow HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: SenseverFlow-Webhooks/1
Webhook-Id: 0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70
Webhook-Timestamp: 1789560000
Webhook-Signature: v1=<base64 HMAC-SHA256>The body is an event envelope:
{
"event_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70",
"event_type": "object.updated",
"schema_version": 1,
"tenant_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71",
"aggregate": {"type": "object", "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72", "version": 28},
"object_type": "deal",
"occurred_at": "2026-09-16T10:00:00.123456Z",
"actor": {"type": "user", "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b74"},
"correlation_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b75",
"causation_id": null,
"depth": 0,
"chain": [],
"payload": {"changed_fields": ["amount"], "changes": {"amount": {"old": 900, "new": 1200}}}
}Field | Description |
|---|---|
| Event id, equal to the |
| Event type |
| Version of the event's shape. New optional keys are added without changing it |
| Workspace |
|
|
| Object type key or |
| Event time, UTC |
| Who acted: |
| End-to-end chain id and the id of the causing event |
| Depth and ids of the automations that led to the event |
| Event data |
Hidden fields. Fields the subscription's principal can't read are absent from
fields,changesandchanged_fields. A change to hidden fields only arrives withchanges: {}andchanged_fields: [].Size. The body is no larger than 256 KB. If an event is larger, the
fieldsandchangesvalues are removed,changed_fieldsremains, andpayloadgets"fields_truncated": true. Fetch current values viaGET /objects/{id}.
Verifying the signature
signature = base64( HMAC-SHA256( secret, Webhook-Id + "." + Webhook-Timestamp + "." + body ) )
Webhook-Signature: v1=<signature>secretis the entire secret string as the API issued it (includingwhsec_), in UTF-8.bodyis the raw bytes of the body. Don't parse or re-serialize the JSON before verifying.The header may contain several signatures separated by spaces (
v1=… v1=…) — the request is authentic if any of them matches.Compare signatures in constant time.
Reject the request if
Webhook-Timestampdiffers from the current time by more than 5 minutes.
Node.js
import crypto from 'node:crypto';
import express from 'express';
function verifyFlowWebhook(secret, headers, rawBody, toleranceSec = 300) {
const id = headers['webhook-id'] ?? '';
const ts = headers['webhook-timestamp'] ?? '';
const sig = headers['webhook-signature'] ?? '';
if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;
const expected = Buffer.from('v1=' + crypto
.createHmac('sha256', secret)
.update(`${id}.${ts}.`)
.update(rawBody)
.digest('base64'));
return sig.trim().split(/\s+/).some((candidate) => {
const got = Buffer.from(candidate);
return got.length === expected.length && crypto.timingSafeEqual(got, expected);
});
}
const app = express();
app.post('/flow', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifyFlowWebhook(process.env.FLOW_WEBHOOK_SECRET, req.headers, req.body)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString('utf8'));
// store the event in your queue by event.event_id and respond right away
res.sendStatus(204);
});Python
import base64, hashlib, hmac, time
def verify_flow_webhook(secret: str, headers, body: bytes, tolerance: int = 300) -> bool:
msg_id = headers.get("Webhook-Id", "")
ts = headers.get("Webhook-Timestamp", "")
sig = headers.get("Webhook-Signature", "")
if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
return False
digest = hmac.new(secret.encode(), f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
expected = "v1=" + base64.b64encode(digest).decode()
return any(hmac.compare_digest(expected, c) for c in sig.split())
# Flask: request.get_data() is the raw body; call it before request.jsonTest vector
Secret whsec_test_secret_0123456789abcdef, Webhook-Id = e, Webhook-Timestamp = 1789000000, body {"event_id":"e"}. The correct header is Webhook-Signature: v1=emf44WORwLg2k8ie9zU70SOOohYBgY7MKWHSaoOPzug=:
printf 'e.1789000000.{"event_id":"e"}' | openssl dgst -sha256 -hmac 'whsec_test_secret_0123456789abcdef' -binary | base64Response and retries
Response. Any
2xxmeans the event is accepted. The request timeout is 10 seconds: store the event and respond right away, and process it afterwards.Failure is everything else:
3xx,4xx,5xx, a timeout, a TLS or connection error. Flow doesn't follow redirects;301and302are failures too."At least once" delivery. One event can arrive several times. Discard duplicates by
Webhook-Id(which is alsoevent_id) and keep processed ids for at least 8 days. For a single entity,aggregate.versionstrictly increases: an event with a version not greater than one already processed can be skipped.Order isn't guaranteed. Retries of one event don't hold back the next ones.
Attempt | Delay before it | Since the first attempt |
|---|---|---|
1 | — | 0 |
2 | 1 min | 1 min |
3 | 5 min | 6 min |
4 | 30 min | 36 min |
5 | 1 h | 1 h 36 min |
6 | 3 h | 4 h 36 min |
7 | 6 h | 10 h 36 min |
8 | 12 h | 22 h 36 min |
Each delay is randomly extended by up to 10%. A 429 or 503 response with Retry-After (seconds or an HTTP date) extends the delay, but to no more than 12 hours. After the eighth failure, delivery of the event stops, and the last attempt in the log gets the status dead.
Automatic disabling
50 failed attempts in a row across all of a subscription's events — the subscription is disabled:
enabled: false,disabled_reason: "consecutive_failures", and theintegration.webhook_disabledevent is published. Unsent deliveries are cancelled. A successful attempt resets theconsecutive_failurescounter.A member is removed or deactivated in the workspace — their subscriptions are disabled with
disabled_reason: "principal_disabled", and their API keys are revoked. After a new invitation, the subscriptions don't come back on their own: an administrator enables them.A person's Sensever account is deactivated — events aren't sent to their subscriptions, but the subscription stays enabled; once the account is reactivated, delivery resumes. Events from the deactivation period aren't delivered. Changing the password or "sign out everywhere" doesn't affect webhooks.
To enable a subscription again, send PATCH with {"enabled": true}.
Delivery log
GET /webhook-subscriptions/{id}/deliveries returns delivery attempts, newest first, paginated (page[size] 1–200, page[cursor]). One row is one attempt. The log is kept for 30 days; the body of your response isn't stored.
Field | Description |
|---|---|
| The event, same as |
| Attempt number |
|
|
| HTTP code of your response or |
| Duration |
| Reason: |
| Attempt time |
Test delivery
POST /webhook-subscriptions/{id}/test with no body immediately sends a signed webhook.test event with payload {subscription_id, test} — even to a disabled subscription — and returns the attempt (status: succeeded or failed). The attempt goes into the log but doesn't affect the failure counter. Repeating with the same Idempotency-Key returns the stored result without sending again.
Rotating the secret
POST /webhook-subscriptions/{id}/rotate-secret with a {"secret": "…"} body or with no body (then Flow creates the secret itself). The new secret is returned once, and the old one stops working immediately — there is no transition period. A safe order:
Make the recipient accept a signature made with either of the two secrets.
Rotate the secret and store the new one.
Remove the old secret from the recipient.
URL requirements
Only
httpsand port 443. A username and password in the URL are not allowed.The hostname must resolve only to public addresses. Private, loopback and link-local addresses are rejected on creation (
422 VALIDATION_FAILED) and checked again on every delivery (blocked_addressin the log).Redirects aren't followed.
Recipient security
Verify the signature and timestamp before any processing; reject requests without a signature.
Keep the secret outside your code; rotate it if you suspect a leak.
Don't treat the sender's IP or the event's contents as proof of permissions: when in doubt, re-read the data through the API with your own key.
Don't return secrets or personal data in your response.
评论