Create Webhook

curl --request POST \
  --url https://api.flowiq.live/set-webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://your-server.com/webhook",
  "type": "message_received"
}
'

{
  "success": true,
  "message": "Webhook created successfully",
  "webhook": {
    "id": "0df9d480-f181-466b-ae8d-85216c16e8dd",
    "url": "https://your-server.com/webhook",
    "type": "message_received",
    "platform": "whatsapp",
    "auth_type": "none",
    "created_at": "2026-03-08T00:00:00.000+02:00"
  }
}

POST

set-webhooks

curl --request POST \
  --url https://api.flowiq.live/set-webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://your-server.com/webhook",
  "type": "message_received"
}
'

{
  "success": true,
  "message": "Webhook created successfully",
  "webhook": {
    "id": "0df9d480-f181-466b-ae8d-85216c16e8dd",
    "url": "https://your-server.com/webhook",
    "type": "message_received",
    "platform": "whatsapp",
    "auth_type": "none",
    "created_at": "2026-03-08T00:00:00.000+02:00"
  }
}

Basic Usage

curl -X POST "https://api.flowiq.live/set-webhooks" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook", "type": "message_received"}'

Request Body

Field	Required	Description
`url`	Yes	HTTPS endpoint to receive events
`type`	Yes	Event type: `message_received`, `message_sent`, `sent_message`, `message_delivered`, `message_read`, `message_failed`, `call`, or `all`
`platform`	No	`whatsapp` (default), `web` or `instagram`. See Events for what each platform fires
`auth_type`	No	How FlowIQ authenticates to your server: `none` (default), `bearer`, `basic`, `api_key`, or `oauth2_client_credentials`
`auth_config`	No	Credentials for the chosen `auth_type` (see below). Required unless `auth_type` is `none`
`headers`	No	Object of extra static headers sent with every delivery, e.g. `{"X-Tenant": "shop-1"}`
`secret`	No	Signing secret. When set, every delivery carries an `X-Flowiq-Signature` header you can verify (how)

{
  "url": "https://your-server.com/webhook",
  "type": "message_received"
}

Instagram

Instagram webhook support is prepared for rollout and is not yet deployed.

Use platform: "instagram" to receive Instagram events. Registration, authentication and signatures work the same as WhatsApp.

curl -X POST "https://api.flowiq.live/set-webhooks" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/instagram",
    "platform": "instagram",
    "type": "all",
    "secret": "a-long-random-string"
  }'

Instagram supports message_received, sent_message, message_sent, message_delivered, message_read, message_failed and all. Receipt events fire only when the state is recorded. call is WhatsApp-only. See Instagram Events for payloads.

Authentication

By default deliveries are sent with no credentials. Set auth_type and auth_config to have FlowIQ authenticate to your server on every delivery.

`auth_type`	Required `auth_config` fields	Optional fields	What FlowIQ sends
`bearer`	`token`		`Authorization: Bearer <token>`
`basic`	`username`, `password`		`Authorization: Basic <base64(username:password)>`
`api_key`	`value`	`header_name` (default `X-API-Key`)	`<header_name>: <value>`
`oauth2_client_credentials`	`token_url`, `client_id`, `client_secret`	`scope`, `audience`, `client_auth`	`Authorization: Bearer <access_token>` from your token endpoint

OAuth2 client credentials. FlowIQ requests a token from token_url with grant_type=client_credentials (plus scope / audience if set), sending the client credentials as HTTP Basic auth. Set client_auth to "body" if your server expects client_id and client_secret in the form body instead. Tokens are cached and refreshed shortly before expires_in runs out.

If FlowIQ can’t build the configured authentication (for example your token endpoint is down or rejects the credentials), that delivery is skipped. It is never sent without the credentials you configured.

Examples

{
  "url": "https://your-server.com/webhook",
  "type": "all",
  "auth_type": "bearer",
  "auth_config": { "token": "YOUR_TOKEN" }
}

{
  "url": "https://your-server.com/webhook",
  "type": "all",
  "auth_type": "api_key",
  "auth_config": { "header_name": "X-Api-Key", "value": "YOUR_KEY" }
}

{
  "url": "https://your-server.com/webhook",
  "type": "all",
  "auth_type": "oauth2_client_credentials",
  "auth_config": {
    "token_url": "https://auth.your-server.com/oauth/token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "scope": "webhooks.write"
  },
  "secret": "a-long-random-string"
}

Response

Returns 201 Created. Credentials and the signing secret are never returned.

{
  "success": true,
  "message": "Webhook created successfully",
  "webhook": {
    "id": "0df9d480-f181-466b-ae8d-85216c16e8dd",
    "url": "https://your-server.com/webhook",
    "type": "message_received",
    "platform": "whatsapp",
    "auth_type": "none",
    "created_at": "2026-03-08T00:00:00.000+02:00"
  }
}

Error: Incomplete Authentication (400)

Returned when auth_type is unknown or its required auth_config fields are missing:

{
  "error": "Invalid auth configuration",
  "message": "auth_config.token is required for auth_type 'bearer'"
}

Use type: "all" to receive every event type through a single webhook subscription.

Webhooks can’t be edited through the API. To change one, delete it and create it again, or edit it in the FlowIQ dashboard.

Authorizations

Authorization

string

header

required

Your FlowIQ API key (from Settings → Profile → API Keys), sent as a bearer token. Format: Bearer fiq_YOUR_API_KEY

Body

application/json

url

string

required

HTTPS endpoint to receive events

Example:

"https://your-server.com/webhook"

type

enum<string>

required

Event type to subscribe to. call is WhatsApp-only; Instagram receipt events fire only when that state is recorded.

Available options:

message_received,

message_sent,

sent_message,

message_delivered,

message_read,

message_failed,

call,

all

Example:

"message_received"

platform

enum<string>

default:whatsapp

whatsapp (default), web, or instagram.

Available options:

whatsapp,

web,

instagram

Example:

"whatsapp"

auth_type

enum<string>

default:none

How FlowIQ authenticates to your server on every delivery

Available options:

none,

bearer,

basic,

api_key,

oauth2_client_credentials

auth_config

object | null

Credentials for auth_type. bearer: token. basic: username, password. api_key: value, optional header_name (default X-API-Key). oauth2_client_credentials: token_url, client_id, client_secret, optional scope, audience, client_auth (basic default, or body).

Show child attributes

Example:

{ "token": "YOUR_TOKEN" }

headers

object | null

Extra static headers sent with every delivery

Show child attributes

Example:

{ "X-Tenant": "shop-1" }

secret

string | null

Signing secret. When set, each delivery carries X-Flowiq-Signature: sha256=<hex HMAC-SHA256 of the raw body>.

Response

Webhook created successfully. Credentials and the signing secret are never returned.

success

boolean

message

string

webhook

object

Show child attributes

Get Started

WhatsApp

Instagram

Webhooks

Reporting & AI

Basic Usage

Request Body

Instagram

Authentication

Examples

Response

Error: Incomplete Authentication (400)

Authorizations

Body

Response

​Basic Usage

​Request Body

​Instagram

​Authentication

​Examples

​Response

​Error: Incomplete Authentication (400)

Authorizations

Body

Response

Basic Usage

Request Body

Instagram

Authentication

Examples

Response

Error: Incomplete Authentication (400)