Why you might encounter repeated webhook events due to non-2xx status codes

This article explains the issue of repeated webhook events when a resource returns a non-2xx status code, detailing the cause, Customerly's retry mechanism, and potential solutions.

Written by ElenaLast update 20 days ago

Webhook integrations are a powerful way to automate and streamline interactions between different web services. However, issues can arise when dealing with various HTTP status codes. One common issue is the repeated triggering of events due to non-2xx status codes.

Understanding HTTP Status Codes

HTTP status codes indicate the result of the request made to the server. They are grouped into categories:

  • 2xx Success: The request was successfully received, understood, and accepted.

  • 3xx Redirection: Further action needs to be taken to complete the request.

  • 4xx Client Errors: The request contains bad syntax or cannot be fulfilled.

  • 5xx Server Errors: The server failed to fulfill an apparently valid request.

When a webhook URL returns a status code outside the 2xx range, it means the request was not completely successful, and further action may be needed.

Why Events Are Repeated

When Customerly's webhook endpoint receives a response that is not a 2xx status code, it interprets this as a failure to deliver the webhook payload. This behavior is due to the assumption that a successful delivery must return a 200 OK status code. As a result, Customerly retries sending the webhook multiple times, leading to repeated events.

Customerly's Retry Mechanism

Customerly's system is designed to retry webhook deliveries up to a maximum of 5 times if the response code is anything other than a 2xx status code. This includes any 3xx, 4xx, or 5xx responses. The retries are spaced out over increasing intervals to give time for temporary issues to resolve.

How to Resolve the Issue

Here are steps you can take to resolve the issue of repeated events due to non-2xx status codes:

  1. Ensure URL Stability:

    • Verify that the webhook URL is stable and not subject to redirections or other issues that might result in non-2xx responses. If the URL is expected to change, update it promptly in Customerly's webhook settings.

  2. Handle Redirections Correctly:

    • If redirections are necessary, ensure that the new URL eventually returns a 200 status code after following the redirection. This might involve configuring the server to handle redirections properly.

  3. Check Response Codes:

    • Make sure that the server handling the webhook responds with a 200 OK status code once it successfully processes the webhook event. Tools like Postman can be used to test and ensure the correct response is being returned.

  4. Monitor and Log:

    • Implement logging for webhook events and responses to monitor status codes and identify any issues with redirections or repeated events.

Example Scenario

In a typical scenario, you might notice multiple entries for the same event due to repeated webhook triggers. Logs indicating status codes like 302 (Redirection), 404 (Not Found), or 500 (Internal Server Error) suggest issues that need to be addressed. By resolving these issues and ensuring the server returns a 200 status code, you can prevent repeated events.

Did this answer your question?