Outbound Webhooks

Receive real-time notifications when data changes in Flowstate. Configure webhook endpoints to push events to your systems whenever employees, teams, projects, allocations, and other entities are created, updated, or deleted.

Overview

Flowstate webhooks deliver events from all entry points:

GraphQL mutations — direct changes by users in the UI
REST API — changes made via API keys
Scenario merges — when a plan/scenario is merged to live data (including changes made via MCP tools and AI chat)

Events are delivered asynchronously. Mutations are never blocked by slow or failing endpoints.

Configuring endpoints

There are no REST endpoints for managing webhook configuration. You configure outbound webhooks in the app at Settings → Webhooks (/settings/webhooks).

Each webhook endpoint has:

Option	Description
Name	Display name (max 100 characters), e.g. "HRIS Sync Endpoint"
Endpoint URL	The HTTPS URL that receives event deliveries
Entity types	The entity types to subscribe to (see table below). Events are only delivered for subscribed types.
Event types	Any combination of `create`, `update`, `delete`
Enabled	A per-endpoint toggle. Disabled endpoints receive no deliveries but keep their configuration.

When you create an endpoint, Flowstate generates a signing secret and shows it once. Store it securely; it is not shown again. From the endpoint's actions menu you can also:

Test Connection: sends a test delivery so you can verify reachability and your signature verification.
Rotate Secret: generates a new signing secret and shows it once. Update your handler immediately after rotating; the old secret stops being valid.

The settings page shows each endpoint's last delivery time and result, so you can spot failing endpoints at a glance.

Entity Types

Subscribe to the specific entity types you need. Events are only delivered for entity types your endpoint is subscribed to.

Core Entities

Entity Type	Description
`employee`	Full-time and part-time staff members
`team`	Organizational teams and hierarchy
`project`	Projects with timelines and cost tracking
`contractor`	External contractors and consulting firms
`vacancy`	Open positions and hiring pipeline
`user`	Platform user accounts
`initiative`	The finance/governance anchor (cost centre, Finance Mode, budget, rollups)

Allocations

Entity Type	Description
`employee_team_allocation`	Employee assignments to teams (with FTE)
`employee_project_allocation`	Employee assignments to projects (with FTE)
`team_project_allocation`	Team assignments to projects (with FTE)
`contractor_team_allocation`	Contractor assignments to teams
`contractor_project_allocation`	Contractor assignments to projects
`vacancy_team_allocation`	Vacancy assignments to teams
`vacancy_project_allocation`	Vacancy assignments to projects

Compensation

Entity Type	Description
`salary_adjustment`	Employee salary changes (effective-dated)
`bonus`	Employee bonus records
`contractor_rate`	Contractor rate adjustments

Reference Data

Entity Type	Description
`cost_center`	Budget tracking and financial allocation
`value_stream`	Business capability groupings for projects
`driver`	Project business driver types
`objective`	Strategy layer above Initiatives (with Key Results)
`portfolio_lens`	Finance-sliceable Initiative classification (KTLO / Revenue / …)
`capex_claim`	CapEx/R&D claim headers (Initiative-anchored or ad-hoc)
`exchange_rate`	Currency conversion rates
`geography`	Geographic locations (labelled Locations in the app)

AI

Entity Type	Description
`ai_agent`	Resourced AI agents (planned AI workers)
`agent_policy`	Agent policy configuration changes
`ai_policy`	AI usage policy changes

Event Types

Event	Description
`create`	A new entity was created. `before` is `null`.
`update`	An existing entity was modified. Both `before` and `after` are present.
`delete`	An entity was deleted. `after` is `null`.

Payload Format

Every webhook delivery is an HTTP POST with a JSON body:

json

{
  "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8g",
  "timestamp": "2026-03-18T15:30:00.000Z",
  "entity_type": "employee",
  "entity_id": "clx1a2b3c4d5e6f7g8h9",
  "change_type": "create",
  "initiator": {
    "type": "user",
    "id": "clx9u8s7e6r5",
    "email": "jane.chen@acme.com"
  },
  "organization_id": "clx9o8r7g6i5d4",
  "before": null,
  "after": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "firstName": "Alex",
    "lastName": "Rivera",
    "email": "alex.rivera@acme.com",
    "startDate": "2026-04-01T00:00:00.000Z",
    "jobRoleId": "clx9r8q7w6e5",
    "geographyId": "clx3g2h1j0k9",
    "defaultCurrencyCode": "GBP"
  }
}

Payload Fields

Field	Type	Description
`id`	string (UUID)	Unique event identifier (for idempotency)
`timestamp`	string	ISO 8601 timestamp of when the event occurred
`entity_type`	string	Entity type (see tables above)
`entity_id`	string (CUID)	ID of the affected entity
`change_type`	string	`create`, `update`, or `delete`
`initiator.type`	string	Who triggered the change (see below)
`initiator.id`	string	ID of the actor (user ID or API key ID)
`initiator.email`	string or null	Email of the actor (present for `user` type)
`organization_id`	string (CUID)	Organization the event belongs to
`before`	object or null	Entity state before the change (`null` for creates)
`after`	object or null	Entity state after the change (`null` for deletes)

Initiator Types

Type	Description
`user`	Change made by an authenticated user via the UI or GraphQL
`api_key`	Change made via the REST API with an API key
`merge`	Change applied by merging a scenario (covers MCP tools, AI chat)
`system`	System-triggered change (reserved for future use)

Signature Verification

Every delivery includes an HMAC-SHA256 signature in the X-Flowstate-Signature header. Verify this signature to ensure the payload was sent by Flowstate and has not been tampered with.

Headers

Header	Description
`X-Flowstate-Signature`	`sha256=<hex-encoded HMAC>`
`X-Flowstate-Event-Id`	Unique event UUID (same as `id` in body)
`Content-Type`	`application/json`

Verification Example (Node.js)

javascript

import crypto from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/flowstate/webhook', (req, res) => {
  const signature = req.headers['x-flowstate-signature'];
  const rawBody = req.body; // Must be the raw string, not parsed JSON

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  console.log(`Received ${event.change_type} on ${event.entity_type}: ${event.entity_id}`);

  res.status(200).send('OK');
});

Verification Example (Python)

python

import hmac
import hashlib

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Secret Rotation

Rotate the signing secret from the endpoint's actions menu at Settings → Webhooks. The new secret is shown once. Update your handler immediately after rotating; the old secret stops being valid as soon as it is rotated.

Test Delivery

Use Test Connection on the endpoint at Settings → Webhooks to verify your endpoint is reachable and your signature verification works. Flowstate delivers a test event with entity_type: "employee", change_type: "create", and sample data.

Delivery Behaviour

Property	Value
Timeout	5 seconds per delivery attempt
Method	`POST` with `Content-Type: application/json`
Deduplication	Use `X-Flowstate-Event-Id` or `id` in the payload for idempotency
Ordering	Events are delivered in approximate order but not guaranteed
Plan mode	Changes within a scenario do NOT fire webhooks
Merge	When a scenario is merged, one event fires per entity changed

INFO

Your endpoint should return a 2xx status code to acknowledge receipt. Non-2xx responses are logged as failures. The delivery timeout is 5 seconds — if your processing takes longer, acknowledge the event immediately and process it asynchronously.

Best Practices

Always verify signatures. Reject requests with missing or invalid X-Flowstate-Signature headers to prevent spoofing.
Use the event ID for idempotency. In rare cases, the same event may be delivered more than once. Use the id field to deduplicate on your end.
Respond quickly. Return 200 OK as soon as you receive the event. Process the payload asynchronously if needed.
Subscribe only to what you need. Each endpoint can filter by entity type and event type. Subscribing to fewer types reduces noise and delivery volume.
Monitor delivery status. Check each endpoint's last delivery result at Settings → Webhooks periodically. Persistent failures may indicate endpoint issues or network problems.
Rotate secrets regularly. Treat the signing secret like a credential. Rotate it on a schedule that matches your security policy.

Outbound Webhooks ​

Overview ​

Configuring endpoints ​

Entity Types ​

Core Entities ​

Allocations ​

Compensation ​

Reference Data ​

AI ​

Event Types ​

Payload Format ​

Payload Fields ​

Initiator Types ​

Signature Verification ​

Headers ​

Verification Example (Node.js) ​

Verification Example (Python) ​

Secret Rotation ​

Test Delivery ​

Delivery Behaviour ​

Best Practices ​