From 1932ce63a8c34a1eba72f11aafa8de4e9bf8b0af Mon Sep 17 00:00:00 2001
From: a-diarra <68294452+a-diarra@users.noreply.github.com>
Date: Thu, 30 Apr 2026 14:51:17 +0100
Subject: [PATCH] clarifying the 'at-least-once' delivery approach followed by
 Svix to deliver our webhooks

---
 docs/using-the-api/webhooks/troubleshooting.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/using-the-api/webhooks/troubleshooting.md b/docs/using-the-api/webhooks/troubleshooting.md
index 4bae896d9..17d449d81 100644
--- a/docs/using-the-api/webhooks/troubleshooting.md
+++ b/docs/using-the-api/webhooks/troubleshooting.md
@@ -71,7 +71,8 @@ During the recovery of multiple messages, we will send all messages at once, app
 
 ### Idempotency
 
-Whilst the Codat system's webhook functionality aims for exactly once delivery of a message, due to the fact messages can be resent, this isn't always possible to guarantee. If idempotency is important for your system, we recommend making use of the HTTP request's webhook-id header, which functions as an idempotency key for a given message, (i.e remains constant across all attempts to deliver that message), and can therefore be used by your system to ensure messages are not reprocessed.
+Codat's webhook service uses an at-least-once delivery model. This means every message is guaranteed to be delivered, but under certain conditions — such as high load or network instability — the same message may be delivered more than once.
+We recommend building your webhook handler to be idempotent. To do this, use the webhook-id header included in every HTTP request. This value stays the same across all delivery attempts for a given message, so you can use it to detect and discard duplicates before processing.
 
 ## Endpoint failures