How do I handle duplicate webhook events?

Catena uses an at-least-once delivery model, which means the same event may be delivered more than once in rare cases, particularly during retries. Your webhook handler should be idempotent, meaning processing the same event twice produces the same result as processing it once.

Two fields help with deduplication:

• X-Request-ID header: a unique ID for each delivery attempt. If you receive the same X-Request-ID twice, it is a duplicate delivery of the same attempt.
• delivery_attempt in the payload: increments with each retry. A value greater than 1 means Catena is retrying a previously failed delivery.

The recommended approach is to store the id field from each event payload in your database with a unique constraint. Before processing, check if that ID has already been handled. If it has, discard the duplicate. Use the occurred_at field within each record in the data array to determine chronological order, not the outer timestamp.