Retry requests safely with idempotency keys

A request can succeed in Flownally and still look failed to you, for example when the connection drops before the response arrives. Without a key, retrying it can send the customer the same order update twice.

What is an idempotency key?

An idempotency key is a string you generate that names one action, such as "send the confirmation for order 4827". You send it in the Idempotency-Key header. When the same request arrives again with the same key, Flownally doesn't apply it a second time.

• The header is optional. Without it, a retried request can send the message twice.
• A key is 1 to 255 characters long.
• Keys belong to the workspace. They aren't scoped to an API key or a conversation.
• The key comes back on the message as clientMessageId, so you can match the message to your order.

Why do store integrations need idempotency keys?

Store integrations repeat requests more often than you'd expect:

• Your HTTP client times out after Flownally has already accepted the message, and your job retries.
• Your store reports the same order event twice. Shopify delivers a webhook again when it doesn't get 200, and WooCommerce can fire a status hook twice.
• A queue worker crashes after the send and runs the job again.
• Flownally answers 503 with code messaging_messaging_send_result_pending. That response must be retried with the same key.

With the same key on each repeat, the customer gets one WhatsApp message. A contact event is recorded once, so it triggers your journeys once.

Which endpoints accept an idempotency key?

Contact events also accept the key as idempotencyKey in the JSON body. The deprecated POST /events takes a key the same way.

Other POST operations don't take a key. POST /contacts is one of them, so search for a customer before you create them, as shown in Sync store customers and phone numbers.

How do I build a good idempotency key?

Build the key from the record that should cause exactly one action: your store, the order and the update.

• Derive it from your own data. A key like {store}-order-{orderId}-{status} comes out the same when a job restarts or a webhook repeats.
• Don't generate a random value on each attempt. A new UUID per retry makes every attempt a new message. If you prefer UUIDs, create one with the job and store it with the job.
• Use one key per message. Two updates for the same order need two keys, and so do a text message and the template that replaces it.
• Leave personal data out. The key comes back as clientMessageId and ends up in your logs, so use order IDs rather than phone numbers or email addresses.

How do I retry a message without sending it twice?

Retry with the same key and the same body, and only when a retry can help.

Build the request body once, before the first attempt. If the text or the template parameters change between attempts, for example because they include the current time, the retry is a different request and fails with 409.

The code samples retry network errors, timeouts, 429 and 5xx responses with the same key, and throw anything else with its status. With curl, --retry repeats timeouts and 408, 429, 500, 502, 503 and 504 responses with the same headers, so each attempt carries the same key:

curl -X POST "https://api.flownally.com/v1/messages" \
  --retry 4 --retry-connrefused --max-time 15 \
  -H "Authorization: Bearer $FLOWNALLY_API_TOKEN" \
  -H "Idempotency-Key: shopify-anna-store-order-4827-confirmed" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
    "recipient": { "type": "phone", "phoneNumber": "+48123456789" },
    "content": {
      "type": "template",
      "template": {
        "name": "order_confirmed",
        "language": "en",
        "components": [
          {
            "type": "body",
            "parameters": [
              { "type": "text", "text": "Anna" },
              { "type": "text", "text": "#4827" }
            ]
          }
        ]
      }
    }
  }'

Run it twice. Both responses carry the same message id, and the customer gets one message.

Trimmed response:

{
  "message": {
    "id": "msg_d7pj3rljs4umccbo6tdg",
    "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
    "deliveryStatus": "pending",
    "clientMessageId": "shopify-anna-store-order-4827-confirmed"
  }
}

• The body is built once, so every attempt sends the same request.
• 409 and other 4xx responses aren't retried. The helper throws them right away with their status, so you can log them and fix the key. 429 and 5xx responses throw once the attempts run out.

What happens if I reuse a key?

A key covers the request, not the delivery.

• A failed message stays failed. If an accepted message later fails, for example with failureCode messaging_window_closed, a retry with its key returns the same failed message. To send a template instead, use a new key, as shown in Handle the WhatsApp 24-hour reply window.
• Don't resend a message in unknown state. deliveryStatus unknown means the message may have reached the customer. A resend with a new key would be a second message.

How do I record a contact event only once?

Create contact event records an event, and active journeys whose trigger matches it can start a run for the contact. A duplicate event can mean a duplicate journey message.

• Send the key in the header or as idempotencyKey in the body. When you send both, the header wins.
• Treat 409 as success. It means the workspace already has an event with this key, so an earlier attempt was recorded.
• Use a different key for each event. order.paid and order.shipped for the same order need different keys.

Every attempt sends the same key. The code samples use the retry helper from above and treat 409 as success:

curl -X POST "https://api.flownally.com/v1/contacts/con_d7pibvs6gljrc2pfdc1g/events" \
  --retry 4 --retry-connrefused --max-time 15 \
  -H "Authorization: Bearer $FLOWNALLY_API_TOKEN" \
  -H "Idempotency-Key: shopify-anna-store-order-4827-paid" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order.paid",
    "payload": { "orderId": "4827", "total": 129.99, "currency": "PLN" }
  }'

The first request returns 201 with the event. A repeat returns 409.