Flow API: webhooks

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

阅读约 13 分钟

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

  1. You create a subscription: a URL, a list of events and, optionally, an object filter. Flow issues a signing secret.

  2. Flow sends each matching event to the URL as a POST request with a JSON body and an HMAC-SHA256 signature.

  3. Your server verifies the signature, stores the event and responds with 2xx.

  4. If there is no 2xx response, 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

GET /webhook-subscriptions

Create a subscription

POST /webhook-subscriptions

Update a subscription

PATCH /webhook-subscriptions/{id}

Delete a subscription

DELETE /webhook-subscriptions/{id}

Delivery log

GET /webhook-subscriptions/{id}/deliveries

Rotate the secret

POST /webhook-subscriptions/{id}/rotate-secret

Test delivery

POST /webhook-subscriptions/{id}/test

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

url

string

yes

Recipient URL, up to 2048 characters. Only https, port 443; the hostname must resolve only to public addresses

event_types

array

yes

1–64 event patterns: an exact name (object.updated), custom.<key> or a namespace mask (object.*, custom.*, access.*)

object_type_ids

array or null

no

1–100 type ids: only events of objects of these types. null — all events

filter

object or null

no

A condition on the object: {"type": "<type key or id>", "where": {…}} in the query language

principal_id

uuid or null

no

Whose permissions the subscription uses. Defaults to you

enabled

boolean

no

Defaults to true

secret

string or null

no

Your own secret: 24–256 visible ASCII characters. Without it, Flow creates a whsec_…

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 payload contents

object.created

An object was created

type_id, schema_version_id, state, title, owner_id, fields

object.updated

Fields changed

changed_fields, changes: {field: {old, new}}

object.archived, object.restored

An object was archived or restored

cascade_operation_id

object.status_changed

Transition to another status

transition_key, from_state, to_state (id, key, category), reason

object.reminder_due

A due date reminder fired

rule, offset, due date field

relation.added, relation.removed

A relation was added or removed

relation_key, from_object_id, to_object_id, side

custom.<key>

A transition emitted its own event

transition_key

sla.breached

An SLA was breached

sla_key, state_id, entered_at, deadline

automation.run_failed, automation.cycle_detected

An automation failure or loop

run_id, definition_id, error

process.started, process.completed, process.failed, process.cancelled, process.step_completed

Process progress

definition_key, object_id, step_key, outcome

approval.requested, approval.decided

Approval

instance_id, object_id, decision

external.event_received

An external event was accepted

source, external_event_id, event_type, correlation_key

schema.published, lifecycle.published, constraint.published, automation.published, process.published

A definition was published

definition_id, version_id, version

field_index.ready, field_index.failed

A field index was built

field_id, processed_objects

operation.completed, operation.failed

A background operation finished

kind, progress, item_errors

integration.webhook_disabled

A subscription was disabled automatically

subscription_id, reason

access.*

Members, teams, roles or permissions changed

entity and the change

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 POST /objects/{id}/checklists/{field})

object.updated; changes contains the field's full item list, before and after

Tags changed

object.updated with the tags field in changed_fields

A task's parent was set or removed

relation.added or relation.removed on the type's subtask relation

A recurrence created the next task in the series

object.created; actor — {"type": "automation", "id": "<series id>", "on_behalf_of": "<member who set up the recurrence>"}

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

Event id, equal to the Webhook-Id header. Use it to discard duplicates

event_type

Event type

schema_version

Version of the event's shape. New optional keys are added without changing it

tenant_id

Workspace

aggregate

{type, id, version} — the event's entity and its version

object_type

Object type key or null

occurred_at

Event time, UTC

actor

Who acted: {type, id}, plus on_behalf_of for an automation

correlation_id, causation_id

End-to-end chain id and the id of the causing event

depth, chain

Depth and ids of the automations that led to the event

payload

Event data

  • Hidden fields. Fields the subscription's principal can't read are absent from fields, changes and changed_fields. A change to hidden fields only arrives with changes: {} and changed_fields: [].

  • Size. The body is no larger than 256 KB. If an event is larger, the fields and changes values are removed, changed_fields remains, and payload gets "fields_truncated": true. Fetch current values via GET /objects/{id}.

Verifying the signature

signature = base64( HMAC-SHA256( secret, Webhook-Id + "." + Webhook-Timestamp + "." + body ) )
Webhook-Signature: v1=<signature>
  • secret is the entire secret string as the API issued it (including whsec_), in UTF-8.

  • body is 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-Timestamp differs 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.json

Test 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 | base64

Response and retries

  • Response. Any 2xx means 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; 301 and 302 are failures too.

  • "At least once" delivery. One event can arrive several times. Discard duplicates by Webhook-Id (which is also event_id) and keep processed ids for at least 8 days. For a single entity, aggregate.version strictly 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 the integration.webhook_disabled event is published. Unsent deliveries are cancelled. A successful attempt resets the consecutive_failures counter.

  • 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

event_id

The event, same as Webhook-Id

attempt

Attempt number

status

succeeded, failed (will be retried) or dead (final failure)

response_code

HTTP code of your response or null if there was no response

duration_ms

Duration

error

Reason: http_status_<code>, timeout: …, connection_failed: …, blocked_address, dns_failed, blocked_url: <code>, secret_unavailable

created_at

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:

  1. Make the recipient accept a signature made with either of the two secrets.

  2. Rotate the secret and store the new one.

  3. Remove the old secret from the recipient.

URL requirements

  • Only https and 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_address in 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.

评论

作者