Understanding ETIMEDOUT Webhook Behavior in Xendit
When sending webhooks, Xendit needs to determine whether the delivery was successful, failed, or timed out. One scenario you might encounter is the ETIMEDOUT error. This article explains what it means, how it differs from a regular timeout, and how Xendit categorizes these cases.
How Xendit Defines a Timeout
In Xendit's system, a timeout is when a webhook response takes 30 seconds or more from the time it’s sent to the time it’s received (or when no response is received at all).
- Timeout threshold = 30 seconds
- At or above 30 seconds → TIMEOUT
- Below 30 seconds → FAILED (if no valid response is received)
What is ETIMEDOUT?
ETIMEDOUT is a technical error code that indicates a connection timeout. It can happen for various reasons:
- The merchant’s server stopped waiting for a response.
- Network issues (DNS resolution failure, unstable internet, firewall blocks, etc.).
- The connection was closed unexpectedly before a full response was received.
Important: ETIMEDOUT does not always mean the same thing as a Xendit TIMEOUT. It depends on when it happened.
The Two Types of ETIMEDOUT Cases
Case 1 — ETIMEDOUT before 30 seconds
- Response time: less than 30 seconds
- Cause: Merchant-side disconnection, early stop in waiting, or network interruption.
- Xendit categorization: FAILED
- Retry behavior: Eligible for retry according to webhook retry policy.
Case 2 — ETIMEDOUT at or after 30 seconds
- Response time: 30 seconds or more
- Cause: Connection timeout either from Xendit or the merchant after the 30s threshold.
- Xendit categorization: TIMEOUT
- Retry behavior: Not retried (because TIMEOUT is considered final for that attempt).