Understanding ETIMEDOUT Webhook Behavior in CF Vault

When sending webhooks, CF Vault 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 CF Vault categorizes these cases.

How CF Vault Defines a Timeout

In CF Vault'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 CF Vault 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.
CF Vault 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 CF Vault or the merchant after the 30s threshold.
CF Vault categorization: TIMEOUT
Retry behavior: Not retried (because TIMEOUT is considered final for that attempt).