Receive events

// app/api/flow/route.ts
import { FlowMessaging, contentText } from "@flow-engineer/messaging";

const flow = new FlowMessaging();

// Verifies Flow-Signature with FLOW_MESSAGING_WEBHOOK_SECRET, then calls onEvent.
// For message.received, what onEvent returns is sent as the reply.
export const POST = flow.webhooks.handler({
  onEvent: async (event) => {
    if (event.type !== "message.received") return;
    return `You said: ${contentText(event.data.message.content)}`;
  },
});

​

Three ways to receive events

​

Polling: GET /v0/events parameters

​

The event shape

{
  "id": "evt_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "type": "message.received",
  "created_at": "2026-11-03T10:15:00Z",
  "app": "app_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "livemode": true,
  "conversation": {
    "id": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "channel": "telegram",
    "sender": "snd_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "contact": "ct_01JB8ZC3K5M7P9R1T3V5X7Z9B1"
  },
  "data": {
    "message": {
      "id": "msg_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
      "direction": "in",
      "status": "received",
      "content": { "kind": "basic", "text": "Do you deliver to 560103?" }
    }
  },
  "timing": { "received_at": "2026-11-03T10:15:00.012Z", "stored_at": "2026-11-03T10:15:00.020Z", "delivered_at": "2026-11-03T10:15:00.041Z" }
}

​

Event types

​

Register a webhook endpoint

curl https://api.flow.engineer/v0/webhook_endpoints \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/api/flow", "events": ["message.received", "message.failed"]}'

​

Verify the signature

Flow-Signature: t=1791763200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Flow-Event-Id: evt_01JB8ZC3K5M7P9R1T3V5X7Z9B1
Flow-Event-Type: message.received
Flow-Version: 2026-11-01

​

Rotate the signing secret

const { secret } = await flow.webhookEndpoints.rotateSecret("we_...", { overlap_seconds: 3600 });
// Store secret as FLOW_MESSAGING_WEBHOOK_SECRET and deploy within the hour.

import express from "express";
import { FlowMessaging, contentText } from "@flow-engineer/messaging";

const flow = new FlowMessaging();
const app = express();

// The raw body is required: a parsed and re-serialized body will not match.
app.post("/flow", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = await flow.webhooks.constructEvent(req.body, req.header("Flow-Signature"), process.env.FLOW_MESSAGING_WEBHOOK_SECRET!);
  } catch {
    return res.status(400).end();
  }
  if (event.type === "message.received") {
    return res.json(flow.webhooks.reply(`You said: ${contentText(event.data.message.content)}`));
  }
  res.json({});
});

app.listen(3000);

# pip install flow-messaging fastapi
from fastapi import FastAPI, Request, Response
from flow_messaging import WebhookSignatureError, construct_event, content_text, webhook_reply

app = FastAPI()

@app.post("/flow")
async def flow_webhook(request: Request):
    body = await request.body()  # the raw body: a parsed and re-serialized body will not match
    try:
        # The secret defaults to FLOW_MESSAGING_WEBHOOK_SECRET.
        event = construct_event(body, request.headers.get("Flow-Signature"))
    except WebhookSignatureError:
        return Response(status_code=400)
    if event.type == "message.received":
        return webhook_reply(f"You said: {content_text(event.data.message.content)}")
    return {}

// The Go SDK is not published yet, so this checks the signature by hand.
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

func verify(body []byte, header, secret string) bool {
	var ts string
	var sigs []string
	for _, part := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(strings.TrimSpace(part), "=")
		switch k {
		case "t":
			ts = v
		case "v1":
			sigs = append(sigs, v)
		}
	}
	t, err := strconv.ParseInt(ts, 10, 64)
	if err != nil {
		return false
	}
	if d := time.Now().Unix() - t; d > 300 || d < -300 {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte("t." + ts + "."))
	mac.Write(body)
	want := hex.EncodeToString(mac.Sum(nil))
	for _, s := range sigs {
		if hmac.Equal([]byte(want), []byte(s)) {
			return true
		}
	}
	return false
}

func main() {
	secret := os.Getenv("FLOW_MESSAGING_WEBHOOK_SECRET")
	http.HandleFunc("/flow", func(w http.ResponseWriter, r *http.Request) {
		body, _ := io.ReadAll(r.Body)
		if !verify(body, r.Header.Get("Flow-Signature"), secret) {
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		var ev struct {
			Type string `json:"type"`
			Data struct {
				Message struct {
					Content struct {
						Text string `json:"text"`
					} `json:"content"`
				} `json:"message"`
			} `json:"data"`
		}
		_ = json.Unmarshal(body, &ev)
		w.Header().Set("Content-Type", "application/json")
		if ev.Type != "message.received" {
			w.Write([]byte("{}"))
			return
		}
		json.NewEncoder(w).Encode(map[string]any{
			"reply": map[string]any{"kind": "basic", "text": "You said: " + ev.Data.Message.Content.Text},
		})
	})
	http.ListenAndServe(":3000", nil)
}

​

Reply in the webhook response

{ "reply": { "kind": "basic", "text": "Yes, we deliver to 560103." } }

{ "reply": ["Here are the sizes we have.", { "kind": "buttons", "text": "Which size?", "buttons": [{ "id": "s", "label": "Small" }, { "id": "m", "label": "Medium" }] }] }

• An empty body, {}, {"reply": null} or a body that is not a JSON object (plain text such as OK) sends nothing, and is not an error.
• A JSON object with a reply that is not valid, or a body that starts with { but is not valid JSON (a piece that is not a kind object or a string, an unknown kind, an empty list, more than 11 pieces) sends nothing at all, not even the valid pieces. It is recorded on the delivery as an invalid_request error with the reason, which the MCP tool get_webhook_deliveries shows. The delivery counts as delivered and is not retried.
• A piece the send gate refuses (a carousel on Telegram answers 422 unsupported_content) arrives as a message.failed event. Nothing is converted: send what the channel takes instead.

​

Delivery rules

• Answer 2xx within 10 seconds. Anything else, or no answer, is a failed delivery.
• Retries: failed deliveries are retried with backoff for 3 days. After that the event stays in the log, marked failed, and you can read it again with GET /v0/events.
• At least once: a delivery can repeat. Deduplicate on the event’s id (also in Flow-Event-Id).
• Ordered per conversation: events in one conversation arrive in order, one at a time. Later events in that conversation wait behind a failing one, so a slow endpoint holds back only its own conversations. See Order per person.
• Ordering in the log: events are ordered by commit, not by created_at. Reading forward with after never skips an event.
• Disabled endpoints keep their place: nothing is lost from the log.

​

Order per person

• What you send goes out one message at a time per conversation, in the order Flow accepted it. A send the channel refuses for now is retried in its place, and later messages to that person wait for it. A send that fails (message.failed) holds nothing back: the next one goes at once.
• As the person sees it: a message you send as several (a text, then one message per card) arrives in the order you sent the calls, across every endpoint, webhook replies and the stream. On WhatsApp, a message with media holds the next one briefly until WhatsApp reports on it, so the person sees them in the order you sent them.
• What the person sends becomes events in the channel’s order, one at a time per conversation. On Telegram that is Telegram’s own update order: a later message waits briefly for an earlier one still on its way. On WhatsApp it is WhatsApp’s timestamp: each message is held briefly so one whose webhook comes late can still go first. A message that arrives after that wait is delivered when it arrives.
• On iMessage, inbound messages carry no order from the channel, so they become events in the order Flow receives them. Two messages the person sends within about a second of each other can arrive swapped.
• A sandbox join gives conversation.started first, then the join itself as the person’s first message.received, then whatever they send next.
• Webhook retries never reorder a conversation: its next event waits until the one before is delivered, or marked failed after 3 days of retries.
• The stream and GET /v0/events give your app’s events in log order, so one conversation’s events come in order there too.

​

The live stream

const ws = new WebSocket("wss://api.flow.engineer/v0/stream", ["flow", "flow.key." + key]);

​

Related

• Local development: receive events on your laptop through the live stream, with no public URL.
• API: The webhook event, Create a webhook endpoint, List events, Open the live stream.