Events

FlowIQ sends a POST request to your registered webhook URL whenever an event occurs. Each payload includes an event_type field so you can route events accordingly.

Subscribers registered as type all receive every event. Those registered for a specific type (e.g. message_received) only receive that one.

Platforms

Webhooks cover WhatsApp, Web and Instagram conversations (Instagram rollout is pending). When registering a webhook in the FlowIQ dashboard (or with platform on Create Webhook), select the platform you want to listen to. Each platform fires its own set of events described below. To authenticate deliveries to your server or verify that they came from FlowIQ, see Delivery.

Add Messaging Webhook modal with Platform and Event Type selectors

WhatsApp Events

`message_received`

Fired when a user sends you a WhatsApp message.

{
  "event_type": "message_received",
  "whatsapp_id": "27834321234",
  "organization_id": "uuid",
  "timestamp": "2026-03-07T00:00:00.000Z",
  "whatsapp_message_id": "wamid.xxx",
  "message_type": "text | image | video | audio | document | location | button | interactive | sticker | contacts | reaction",
  "message": "Hello there",
  "media_type": null,
  "media_url": null,
  "file_name": null,
  "contact_id": "uuid",
  "reply_context_id": null,
  "location_data": null,
  "reaction": null,
  "reacted_to_message_id": null
}

whatsapp_id is the contact’s phone number with country code (e.g. 27834321234)
media_type / media_url / file_name are populated for image, video, audio, and document messages
location_data is { latitude, longitude, name, address } for location messages
reply_context_id is the wamid of the message being replied to
reaction / reacted_to_message_id are only present when message_type is reaction — reaction is the emoji (e.g. 👍) and reacted_to_message_id is the wamid of the message that was reacted to

`message_sent` (WhatsApp)

Fired when Meta confirms your outbound message was sent (lightweight receipt).

{
  "event_type": "message_sent",
  "whatsapp_id": "27834321234",
  "whatsapp_message_id": "wamid.xxx",
  "organization_id": "uuid",
  "status": "sent",
  "timestamp": "2026-03-07T00:00:00.000Z"
}

`sent_message`

Also fired on sent — but with the full message record so you have the message content.

{
  "event_type": "sent_message",
  "whatsapp_id": "27834321234",
  "id": "uuid",
  "organization_id": "uuid",
  "message": "Hi, here is your order update!",
  "sender_type": "bot-whatsapp",
  "created_at": "2026-03-07T00:00:00.000Z",
  "contact_id": "uuid",
  "message_status": "sent",
  "media_type": null,
  "media_url": null,
  "media_file_name": null,
  "member_id": null,
  "whatsapp_message_id": "wamid.xxx",
  "reply_context_id": null,
  "broadcast_id": null,
  "sent_receipt_received": true,
  "delivered_receipt_received": false,
  "read_receipt_received": false,
  "timestamp": "2026-03-07T00:00:00.000Z"
}

`message_delivered`

{
  "event_type": "message_delivered",
  "whatsapp_id": "27834321234",
  "whatsapp_message_id": "wamid.xxx",
  "organization_id": "uuid",
  "status": "delivered",
  "timestamp": "2026-03-07T00:00:00.000Z"
}

`message_read`

{
  "event_type": "message_read",
  "whatsapp_id": "27834321234",
  "whatsapp_message_id": "wamid.xxx",
  "organization_id": "uuid",
  "status": "read",
  "timestamp": "2026-03-07T00:00:00.000Z"
}

`message_failed`

Fired for failed, undelivered, and warning statuses.

{
  "event_type": "message_failed",
  "whatsapp_id": "27834321234",
  "whatsapp_message_id": "wamid.xxx",
  "organization_id": "uuid",
  "status": "failed | undelivered | warning",
  "timestamp": "2026-03-07T00:00:00.000Z"
}

`call`

Fired when a WhatsApp call event arrives for your number (WhatsApp Business Calling). The body is Meta’s raw webhook payload, with FlowIQ’s fields added at the top level:

{
  "event_type": "call",
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [{ "field": "calls", "value": { "...": "Meta's call event" } }]
    }
  ],
  "organization_id": "uuid",
  "timestamp": "2026-03-07T00:00:00.000Z",
  "phone_number_id": "1234567890"
}

entry is passed through unchanged; see Meta’s Calling API webhooks for its contents
phone_number_id is your WhatsApp number’s Meta phone number ID

Instagram Events

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

Register with platform: "instagram" on Create Webhook. Events describe Instagram activity stored in the FlowIQ inbox, including staff, API, automated and native-app messages when recorded there.

Event	When it fires
`message_received`	An incoming message, comment or story interaction is stored, or a customer reaction changes
`sent_message`	Outgoing message content after Instagram acceptance is recorded
`message_sent`	Instagram acceptance is recorded; contains the status instead of message content
`message_delivered`	A delivered state is recorded
`message_read`	A read state is recorded
`message_failed`	A failed state is recorded
`all`	Subscribes to all of the above

Instagram does not emit call. Delivery, read and failure information depends on what the connection reports and what FlowIQ records. A successful send alone does not imply delivery. Subscription changes apply to future events; history is not replayed.

Identifiers

Field	Meaning
`event_id`	Stable event identifier; use it to deduplicate deliveries
`message_id`, `id`	FlowIQ inbox message UUID (the two fields are aliases)
`instagram_message_id`	Instagram message ID, when available; matches `message_id` from a send response
`contact_id`	FlowIQ contact UUID
`instagram_id`	Contact’s Instagram-scoped ID, as a string
`instagram_username`	Contact’s username, when available
`organization_id`	Organization that owns the message
`platform`	Always `instagram`
`sender_type`	`user-instagram`, `human-instagram` or `bot-instagram`
`timestamp`	Event timestamp; status events use their recorded status time when available

Incoming message

message_received includes the content and media fields. Comment and story identifiers are populated when available. Text messages have message_type: "text" and null media fields.

{
  "event_type": "message_received",
  "event_id": "00000000-0000-4000-8000-000000000001:message_received",
  "organization_id": "00000000-0000-4000-8000-000000000002",
  "platform": "instagram",
  "contact_id": "00000000-0000-4000-8000-000000000003",
  "message_id": "00000000-0000-4000-8000-000000000001",
  "id": "00000000-0000-4000-8000-000000000001",
  "instagram_message_id": "ig.message.example",
  "instagram_id": "17841400000000000",
  "instagram_username": "customer",
  "sender_type": "user-instagram",
  "timestamp": "2026-10-08T10:00:00Z",
  "message": "Hello!",
  "message_type": "text",
  "media_type": null,
  "media_url": null,
  "media_file_name": null,
  "file_name": null,
  "reply_context_id": null,
  "created_at": "2026-10-08T10:00:00Z",
  "message_status": null,
  "instagram_comment_id": null,
  "instagram_story_id": null,
  "instagram_media_id": null
}

Outgoing content and status

sent_message uses the same content fields as the incoming example, with an outgoing sender_type and its own event_id. message_sent, message_delivered, message_read and message_failed carry status instead of the message and media fields. They refer to the same message IDs. For example:

{
  "event_type": "message_read",
  "event_id": "00000000-0000-4000-8000-000000000001:message_read",
  "organization_id": "00000000-0000-4000-8000-000000000002",
  "platform": "instagram",
  "contact_id": "00000000-0000-4000-8000-000000000003",
  "message_id": "00000000-0000-4000-8000-000000000001",
  "id": "00000000-0000-4000-8000-000000000001",
  "instagram_message_id": "ig.message.example",
  "instagram_id": "17841400000000000",
  "instagram_username": "customer",
  "sender_type": "human-instagram",
  "timestamp": "2026-10-08T10:02:00Z",
  "status": "read"
}

Customer reactions

A customer reaction is delivered as message_received with message_type: "reaction". Its message IDs identify the target message, and its event_id includes the reaction timestamp, actor, action and emoji. Reactions made by the connected business account do not generate incoming customer events.

{
  "event_type": "message_received",
  "event_id": "00000000-0000-4000-8000-000000000001:reaction:2026-10-08T10:03:00Z:17841400000000000:react:❤️",
  "organization_id": "00000000-0000-4000-8000-000000000002",
  "platform": "instagram",
  "contact_id": "00000000-0000-4000-8000-000000000003",
  "message_id": "00000000-0000-4000-8000-000000000001",
  "id": "00000000-0000-4000-8000-000000000001",
  "instagram_message_id": "ig.message.example",
  "instagram_id": "17841400000000000",
  "instagram_username": "customer",
  "sender_type": "user-instagram",
  "timestamp": "2026-10-08T10:03:00Z",
  "message": null,
  "message_type": "reaction",
  "media_type": null,
  "media_url": null,
  "media_file_name": null,
  "file_name": null,
  "reply_context_id": null,
  "created_at": "2026-10-08T10:00:00Z",
  "message_status": null,
  "instagram_comment_id": null,
  "instagram_story_id": null,
  "instagram_media_id": null,
  "reaction": "❤️",
  "action": "react",
  "reacted_to_message_id": "ig.message.example"
}

Use the shared delivery headers and signature verification. Acknowledge quickly and process asynchronously. Delivery is best effort, without a durable retry queue.

Web Events

Web webhooks fire for conversations that happen through the FlowIQ web chat widget. Register them by selecting Web as the platform when adding a webhook in the FlowIQ dashboard.

Add Messaging Webhook modal showing Web platform selected

`message_received`

Fired when a web visitor sends a message (sender_type: "user-web").

{
  "event_type": "message_received",
  "organization_id": "uuid",
  "contact_id": "uuid",
  "message_id": "uuid",
  "message": "Hello there",
  "sender_type": "user-web",
  "platform": "web",
  "timestamp": "2026-03-07T00:00:00.000Z",
  "media_type": null,
  "media_url": null,
  "media_file_name": null,
  "more_data": null
}

`sent_message`

Fired when a human agent or AI bot sends a web message (sender_type: "human-web" or "bot-web").

{
  "event_type": "sent_message",
  "organization_id": "uuid",
  "contact_id": "uuid",
  "message_id": "uuid",
  "message": "Hi, how can I help you?",
  "sender_type": "bot-web",
  "platform": "web",
  "timestamp": "2026-03-07T00:00:00.000Z",
  "media_type": null,
  "media_url": null,
  "media_file_name": null,
  "more_data": null
}

sender_type will be "human-web" for messages sent by a support agent, or "bot-web" for AI-generated replies.
media_type / media_url / media_file_name are populated when the message contains a file or image.
more_data contains any additional structured data attached to the message.

Delivery

Each event is sent as a single POST with a JSON body. Register webhooks with Create Webhook or in the FlowIQ dashboard.

Headers

Header	When	Value
`Content-Type`	Always	`application/json; charset=utf-8`
`X-Flowiq-Event`	Always	The event type, same as `event_type` in the body
`Authorization`	`auth_type` is `bearer`, `basic` or `oauth2_client_credentials`	The credential you configured
`X-API-Key` (or your `header_name`)	`auth_type` is `api_key`	Your key
`X-Flowiq-Signature`	A `secret` is set	`sha256=<hex HMAC-SHA256 of the raw body>`
Your custom headers	`headers` is set	As configured

Non-ASCII characters (emoji, accented letters) are sent as JSON \uXXXX escapes, so the body is plain ASCII. Any JSON parser turns them back into the original characters.

Verifying signatures

If you set a secret, compute an HMAC-SHA256 of the raw request body with that secret and compare it to the X-Flowiq-Signature header. Use the bytes exactly as received: parsing and re-serialising the JSON changes them and the signature won’t match.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", process.env.FLOWIQ_WEBHOOK_SECRET).update(req.body).digest("hex");
  const received = req.get("X-Flowiq-Signature") || "";

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  const event = JSON.parse(req.body);
  console.log(event.event_type, event.whatsapp_message_id);
  res.sendStatus(200);
});

import hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhook")
def webhook():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    expected = "sha256=" + hmac.new(
        os.environ["FLOWIQ_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Flowiq-Signature", "")):
        abort(401)

    event = request.get_json()
    print(event["event_type"])
    return "", 200

Delivery behaviour

FlowIQ makes one attempt per event and waits up to 10 seconds for your server. Failed deliveries aren’t retried, so respond with a 2xx quickly and do slow work in the background.
If the configured authentication can’t be built (for example your OAuth token endpoint is down), the delivery is skipped rather than sent without credentials.
Events can arrive out of order. Use timestamp and the platform message ID to reconcile. For Instagram, deduplicate by event_id and group updates by message_id or instagram_message_id.

Get Started

WhatsApp

Instagram

Webhooks

Reporting & AI

Platforms

WhatsApp Events

`message_received`

`message_sent` (WhatsApp)

`sent_message`

`message_delivered`

`message_read`

`message_failed`

`call`

Instagram Events

Identifiers

Incoming message

Outgoing content and status

Customer reactions

Web Events

`message_received`

`sent_message`

Delivery

Headers

Verifying signatures

Delivery behaviour

​Platforms

​WhatsApp Events

​message_received

​message_sent (WhatsApp)

​sent_message

​message_delivered

​message_read

​message_failed

​call

​Instagram Events

​Identifiers

​Incoming message

​Outgoing content and status

​Customer reactions

​Web Events

​message_received

​sent_message

​Delivery

​Headers

​Verifying signatures

​Delivery behaviour

Platforms

WhatsApp Events

`message_received`

`message_sent` (WhatsApp)

`sent_message`

`message_delivered`

`message_read`

`message_failed`

`call`

Instagram Events

Identifiers

Incoming message

Outgoing content and status

Customer reactions

Web Events

`message_received`

`sent_message`

Delivery

Headers

Verifying signatures

Delivery behaviour