Webhook retries and idempotency

Before you begin

• Register an HTTPS endpoint that returns 2xx quickly
• Outbound webhooks may require Pro or Enterprise
• Your endpoint must be publicly reachable (no localhost)

Event delivery

• Flowforce POSTs JSON to your URL on subscribed events
• Failed deliveries retry with exponential backoff
• After max attempts, events move to a dead-letter state — replay from admin when supported
• Verify webhook signature header before processing body

Idempotency

The same event may arrive more than once. Always dedupe by event ID before side effects.

flowforce:{event_type}:{event_id}

Handler checklist

• 1. Verify signature
• 2. Parse JSON and read event_id + event_type
• 3. Skip if idempotency key already processed
• 4. Apply business logic (update CRM, notify Slack, etc.)
• 5. Return 200 within timeout (defer heavy work to a queue)

Retry-friendly responses

• 200 — acknowledged; no further retries
• 4xx (except 429) — do not retry; fix payload or subscription
• 5xx or timeout — Flowforce retries with backoff
• 429 — slow down; retries will continue

Testing

• Use a staging endpoint and separate webhook secret
• Log raw payload hash (not PII) for debugging
• Replay test events from admin tools when available

Common issues

• Duplicates creating double records — implement idempotency store
• Signature failures — clock skew or wrong signing secret
• Timeouts — return 200 fast and process async
• No events — confirm subscription active and endpoint URL is HTTPS