iMessage webhooks: signing, retries and ordering

Building on the iMessage API? Build on iMessage with Flow: one agent for iMessage, WhatsApp and Telegram. New to it? Read the iMessage API guide.

What a webhook has to do

When someone writes to your iMessage line, the provider posts an event to your HTTPS endpoint. That one request has to be trustworthy and survivable. Four things make it so:

1. Signed. You can prove the request came from the provider.
2. Retried. A short outage on your side does not lose the message.
3. Deduplicated. Retries and redeliveries do not run your action twice.
4. Replayable. You can fetch what you missed.

The iMessage API guide covers the surrounding design. This post is about the delivery itself, using Flow’s events docs.

Verify the signature

Every Flow delivery carries these headers:

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

v1 is the lowercase hex HMAC-SHA256, keyed with the endpoint secret, of the string t.{t}.{body}: the letter t, a dot, the timestamp, a dot, and the raw request body exactly as received. Compare in constant time and reject timestamps more than five minutes from your clock.

The SDKs do this for you. In 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();
  }
  // handle the event
  res.json({});
});

In Python, construct_event(body, request.headers.get("Flow-Signature")) does the same and raises WebhookSignatureError. In Go, check it by hand.

You get the endpoint secret, whsec_..., once, when you create the endpoint with POST /v1/webhook_endpoints. Store it as FLOW_MESSAGING_WEBHOOK_SECRET. A test key’s endpoint receives test events, so going live means registering the endpoint again with the live key.

Retries, duplicates and order

• At least once. Flow’s deliveries are at least once. Deduplicate on the event’s id, which is also in the Flow-Event-Id header.
• Retried for three days. A failed delivery is retried, so an outage of up to three days loses nothing.
• In order per conversation. Flow delivers one event at a time, in order, per conversation.
• Answer fast. Flow waits 10 seconds for the answer. For slow work, return {} at once and send the reply with POST /v1/conversations/{conversation_id}/messages.
• Idempotent replies. Use the event ID as the Idempotency-Key, and a redelivered event cannot make Flow send the webhook-answer reply twice.

Status events such as message.sent and message.delivered are high volume. Each endpoint subscribes only to the event types it lists, so subscribe to what you use.

Recover after downtime

Webhooks, the live stream and polling all read the same log. After an outage you can catch up without guessing:

curl -G https://api.flow.engineer/v1/events \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  --data-urlencode "after=evt_01JB8ZC3K5M7P9R1T3V5X7Z9B1" \
  --data-urlencode "type=message.received"

Events come oldest first, up to 100 a page, and has_more says whether to continue. Events are kept for your plan’s retention, 30 days by default. The live stream resumes from an after ID too, then goes live.

Rotate the secret

POST /v1/webhook_endpoints/{id}/rotate_secret returns a new secret, shown once. The old secret keeps signing for overlap_seconds, one day by default, so during the overlap every delivery carries two v1 values and verifies with either secret. Send an Idempotency-Key with the rotation and retry with the same key. A retry without one is a second rotation.

Put the webhook into your agent

Flow’s signed, ordered and replayable event stream gives your agent a dependable boundary between the channel and your application. For the complete send loop, see Send iMessage programmatically and Build an iMessage AI agent.

Frequently asked questions

Keep reading

All posts: the Flow blog. The Flow docs have the reference.