Webhooks

Webhooks push events to your server in real time, so you don’t have to poll. When something happens in the CRM — a record is created, an SMS arrives — we…

Webhooks push events to your server in real time, so you don’t have to poll. When something happens in the CRM — a record is created, an SMS arrives — we send an HTTP POST to a URL you register.

This page is the catalogue of events you can subscribe to. Registering a subscription, signature verification and delivery are covered in the pages linked at the bottom (added as those endpoints ship).

You can always fetch this catalogue live:

curl -H "x-api-key: $KEY" \
  https://<host>/functions/v1/public-api/v1/webhook-events

---

What an event looks like

Every event has a name and a payload. Names are dot-namespaced and provider-free — message.sms.received, never anything naming the underlying SMS vendor. That’s deliberate: which providers we use is our operational detail, not part of your integration.

The payload carries only the fields listed below. Nothing else is ever included — if an internal system starts recording a new field, it does not silently begin flowing to your endpoint.

---

The catalogue

Records

Event	Fires when
record.created	A record is created in any object (built-in or custom).
record.updated	A record is updated. changed_fields lists what changed.
record.deleted	A record is deleted.

Payload: object, record_id, changed_fields (update only), occurred_at.

Messaging

Event	Fires when
message.sms.received	An inbound SMS arrives.
message.email.received	An inbound email arrives.
message.email.engagement	A sent email is opened or clicked (engagement: open | click).
fax.received	An inbound fax arrives (pages).
call.completed	A voice call completes (outcome, duration_seconds).

Messaging payloads carry record_id when the message is linked to a record, plus event-specific fields and a timestamp. Sender/recipient are normalised and never carry a provider identifier.

Workflow

Event	Fires when
form.submitted	A form is submitted (form).
sla.breached	An SLA is breached (sla).
appointment.scheduled	An appointment is scheduled (scheduled_at).
appointment.rescheduled	An appointment is moved (scheduled_at).
appointment.cancelled	An appointment is cancelled.

---

Notes for building against this

• Treat the catalogue as the contract. Fetch GET /v1/webhook-events and map from name; do not hard-code payload field lists you scraped from a sample.
• New events may be added. Handle an unrecognised event name gracefully (ignore it) rather than erroring — we may publish new events over time.
• Payloads only grow within their whitelist. A field will not appear that isn’t documented here, but treat missing optional fields as normal.

---

Verifying signatures

Every delivery carries a Flow9-Signature header. Verify it before trusting the payload — it proves the request came from Flow9 and hasn’t been replayed.

Flow9-Signature: t=1784800000,v1=5f3c…(64 hex chars)

v1 is HMAC-SHA256(secret, t + "." + rawBody), hex-encoded, where secret is the value shown once when you created the subscription and rawBody is the exact bytes of the request body. The timestamp t is inside the signed material, so an old signature can’t be replayed with a new timestamp. Reject anything where t is more than 5 minutes from your clock.

Verify against the raw body, before JSON-parsing it. Re-serialising parsed JSON can change bytes and break the check.

Node

const crypto = require("crypto");

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  // constant-time compare
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "", "hex").length ? Buffer.from(parts.v1) : Buffer.alloc(0);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Use your platform’s constant-time comparison (crypto.timingSafeEqual, hmac.compare_digest) — a plain == leaks, through timing, how much of the signature matched, which is enough to forge one over many requests.

Filtering deliveries

A subscription can carry a filter so you only receive events that match — for example, only leads from a particular source, or only high-value deals. Filtering happens before delivery: a non-matching event produces no request to your endpoint at all.

The filter uses the same grammar as record filtering:

{ "url": "https://hooks.example.com/flow9",
  "events": ["record.created"],
  "filter": { "and": [
    { "field": "object", "op": "eq", "value": "leads" },
    { "field": "source", "op": "in", "value": ["facebook", "google"] }
  ]}}

• Filter fields must be fields the subscribed events actually carry (see each event’s payload above, plus object and record_id). A filter naming an unknown field is rejected with 422 when you create the subscription, not silently ignored later.
• Operators: eq, neq, gt, gte, lt, lte, contains, in, is_null, combined with and / or nested up to 3 deep.
• Filters are evaluated as data, never executed — values containing punctuation or code are compared literally.

Delivery log, replay and test events

GET  /v1/webhooks/{id}/deliveries                  the delivery log
POST /v1/webhooks/{id}/test                         send a sample event
POST /v1/webhooks/deliveries/{deliveryId}/replay    resend a past delivery

• Delivery log shows each attempt: status, attempts, last response code, and a truncated response snippet — enough to debug a failing consumer.
• Test event enqueues a synthetic delivery with a sample payload for one of the subscription’s events, so you can wire up and verify signature handling before real traffic. It is signed exactly like a real delivery.
• Replay enqueues a fresh copy of a past delivery (new id, signed anew). Replay and test both require settings:configure; replaying another tenant’s delivery is a 404.

Related

• Working with records — the objects that emit record.*
• Authentication and scopes