How Do I Handle Duplicated Webhook Events?

Written by Killiane Menand

Published on October 7, 20241 min read

---

Receiving duplicated webhook events can be confusing, but in many cases, it’s part of normal network behavior. Here’s how you can confirm whether the events are duplicates and what you can do to handle them efficiently.

Confirming Duplicated Events

The easiest way to determine if two events are truly duplicates is by checking the webhookId and sequenceNumber in the response.

• If both the webhookId and sequenceNumber are the same for multiple events, they are duplicates.

• This could happen due to various reasons, often related to network issues or delayed responses.

Common Causes of Duplicate Events

The most common reason for receiving duplicate webhook events is a non-200 response or a delayed response from your endpoint. For example:

• If your endpoint is running on a cloud function (e.g., AWS Lambda), it may take time to start if it’s in a cold start state, resulting in a delay.

• This delay can cause the webhook to retry the event, sending it again, and creating a duplicate.

Plan for Duplicates

While webhook systems aim to minimize duplicates, it’s important to design your system with the possibility in mind, as they can still occur due to various network-related issues. Here’s what you should do:

• Track the webhookId and sequenceNumber in your system to identify duplicates and avoid processing the same event multiple times.

• For additional guidance, check out our Webhook Retry Logic guide!

By planning for duplicates, monitoring your webhookId and sequenceNumber, and ensuring your endpoint responds efficiently, you can handle and reduce duplicated webhook events.