Delivery & Retries

FormantAI retries webhook delivery for transient failures.

Success criteria

Your endpoint should return any 2xx response within 10 seconds.

HTTP/1.1 204 No Content

Retry schedule

Retry conditions

FormantAI retries:

• Network errors
• Timeouts
• HTTP 429
• HTTP 5xx

FormantAI does not retry most 4xx responses because they usually mean the request was rejected permanently.

Timeout

Each delivery attempt has a 10 second timeout. If your workflow needs more time, store the event and process it asynchronously.

Idempotency

Webhook deliveries can be retried. Your endpoint must be idempotent.

Use event_id as the primary dedupe key.

app.post("/webhooks/formant", async (req, res) => {
  const event = req.body;
  const inserted = await insertWebhookEventIfNew(event.event_id, event);
  if (!inserted) {
    return res.status(204).send();
  }
  await enqueueWebhookWork(event.event_id);
  res.status(204).send();
});

Delivery metadata

Delivery attempts are stored on the conversation metadata for debugging. Use the Conversations API and trace_id when investigating missed downstream updates.

Receiver checklist

• Verify the HMAC signature.
• Persist the raw event.
• Dedupe by event_id.
• Return quickly.
• Process business logic in a queue.
• Monitor failure rates and latency.