Custom Integrations

Write JavaScript hooks to sync data between Flowstate and any external system — your internal HRIS, a vendor portal, a billing platform, or anything else with an API. Custom Integrations give you two building blocks:

• PULL hooks fetch data from an external system into Flowstate on a schedule
• PUSH hooks react to changes in Flowstate and send data to an external system in real time

Hook type	Direction	Trigger	Example use case
PULL	External → Flowstate	Scheduled	Import employees from an internal HR system
PUSH	Flowstate → External	Entity change	Notify a billing system when a new contractor is added

When to use Custom Integrations

Use Custom Integrations when:

• Your system isn't covered by a built-in integration
• You need to transform or filter data before it reaches Flowstate
• You want to push Flowstate changes to an internal tool or notification system

Getting started

Enablement required

Custom Integrations must be enabled for your organisation. Contact your account manager to get started.

1. Create an integration

Go to Settings → Data Integrations → Custom Integrations and click New Integration. Give it a name, a description, and a source system key (a short identifier like workday or internal-hr — this is used to match records across syncs).

2. Add your secrets

Under the Secrets tab, add any API keys, tokens, or credentials your hook needs to authenticate with the external system. Secrets are encrypted at rest and only decrypted when your hook runs. They're never visible in the UI after saving.

3. Create a hook

Click Add Hook and choose:

• Hook type — PULL (fetch data in) or PUSH (react to changes)
• Entity type — what kind of data the hook works with (see supported entities)
• Event types (PUSH only) — which changes to listen for: create, update, or delete

4. Write your code

Use the built-in code editor to write your hook. Your code runs as a JavaScript function that receives a context object with an HTTP client, your secrets, a key-value store, and a logger.

See the Writing Hooks guide for full examples.

5. Test with a dry run

Click Test to run your hook in dry-run mode. Dry runs execute your code and show logs, but don't write any data to Flowstate. Use this to verify your hook works before going live.

6. Set a schedule and enable

For PULL hooks, choose a sync schedule (how often to run and at what hour). For PUSH hooks, just toggle the hook on — it will start reacting to changes immediately.

Supported entities

Custom Integrations can sync the following entity types:

Entity type	Description
employee	Full-time and part-time staff
vacancy	Open positions and planned hires
contractor	External workers with rate-based compensation
project	Work initiatives and programmes
assignment	Employee-to-project allocations

See the Data Model Reference for the full list of fields available for each entity type.

Limits

Limit	PULL hooks	PUSH hooks
Memory	128 MB	128 MB
Execution time per page	30 seconds	10 seconds
HTTP requests per page	50 (resets each page)	50
HTTP response size	10 MB	10 MB
Max pages per execution	100	N/A
Max scheduled executions per hour	5	N/A (event-driven)

Key-value store limits

Limit	Value
Key length	256 characters
Value size	64 KB
Default expiry	90 days

How change detection works

When a PULL hook returns records, Flowstate fingerprints each one and compares it against the previous sync. Only new or changed records are written — unchanged records are skipped entirely. This means your hook can return the full dataset every time without worrying about unnecessary writes or duplicate entries.

Dry-run mode

Every hook supports dry-run testing. A dry run:

• Executes your code in the same sandboxed environment as a real run
• Logs all HTTP requests and console output
• Shows which records would be created or updated (PULL hooks)
• Does not write any data to Flowstate

Use dry runs to validate your hook logic, check API responses, and debug issues before enabling a hook for production use.

Execution logs

Every hook execution — scheduled, manual, or test — is recorded with:

• Status (completed, failed, or timed out)
• Duration
• Records processed, created, updated, and skipped (PULL hooks)
• Console logs from ctx.log
• HTTP request log (method, URL, status, duration)
• Error details if the execution failed

View execution history in Settings → Data Integrations → Custom Integrations → [your integration] → [your hook] → Executions.

Next steps

• Writing Hooks — PULL and PUSH examples, scheduling, error handling
• Context API Reference — everything available on the ctx object
• Data Model Reference — fields for each entity type