Skip to main content
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 are supported for both WhatsApp and Web conversations. When registering a webhook in the FlowIQ dashboard, select the platform you want to listen to. Each platform fires its own set of events described below. 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",
  "message": "Hello there",
  "media_type": null,
  "media_url": null,
  "file_name": null,
  "contact_id": "uuid",
  "reply_context_id": null,
  "location_data": 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

​
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"
}

​
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.