Skip to main content
An endpoint normally belongs to one organisation and hears only its events. A bureau running payroll for hundreds of clients should not need an endpoint per client. Set webhooks up once for the whole account, and change the setup for any one organisation when it needs something different.

​
One endpoint for every organisation

Add scope=customer to the query when you create the endpoint:
The endpoint you get back shows "scope": "Customer" and your account in ownerId. You cannot change the scope afterwards. It hears every organisation on your account, including organisations added later: nothing to do when a client joins. You need account-wide access: the account owner, or a user given access to the whole account rather than to individual organisations. Anyone else is refused with 403.

​
Set alert contacts once

Set the account’s default alert contacts once, and every endpoint on every organisation uses them unless it has its own:
Every alert-contacts response shows who is actually emailed and why, in effective.source. See Alert emails.

​
Give one organisation its own settings

To send one client’s events somewhere else, or with different event types or payload style:
  1. Exclude it from the account-wide endpoint: POST /endpoints/{endpointId}/excluded-organisations with {"organisationIds": ["org-123"]}.
  2. Create an endpoint for that organisation, signed in to it, with the settings it needs.
Every other organisation, including ones added later, still goes to the account-wide endpoint. To include the organisation again, DELETE /endpoints/{endpointId}/excluded-organisations/org-123. You can also send excludedOrganisationIds when you create the endpoint or with PATCH /endpoints/{endpointId}.

​
Or hear only some organisations

The opposite: PUT /endpoints/{endpointId}/organisations with {"organisationIds": [...]} limits the endpoint to those organisations. An endpoint either includes chosen organisations or excludes some, never both: sending both is refused with organisation_include_and_exclude.

​
See every endpoint on the account

GET /endpoints?scope=all lists the account-wide endpoints and every organisation’s own endpoints in one list, in the order they were created. Each carries scope and ownerId, so you can tell an account-wide endpoint from an organisation’s. GET /endpoints?scope=customer lists the account-wide ones only. Keep following paginationToken until it is absent.

​
See events across the account

GET /events?scope=customer lists the last 90 days of events for every organisation on the account, newest first, with the same eventType, startDate and endDate filters as for one organisation. Each event carries organisationId. Events of an organisation that has since left your account are not listed. GET /events/{eventId}?scope=customer reads one event from any organisation on the account. To read one from a single other organisation, send organisationId instead; sending both is a 400 with organisation_and_account_scope.

​
Replay across the account

POST /replays?scope=customer resends failed deliveries, or anything you choose, for every endpoint on the account: account-wide and each organisation’s own. Name up to 100 endpointIds to narrow it. It runs in the background; follow it with GET /replays/{replayId}?scope=customer. The replay carries scope and ownerId, as an endpoint does.

​
Limits

​
Tell organisations apart

Every delivery names who it belongs to, in the headers and in the body:
  • X-Flow-Organisation-Id and organisationId: the client organisation.
  • X-Flow-Customer-Id and customerId: your account.
Route on the header if you want to avoid parsing the body before you have verified it.