Notifications Delivery Error: "networkError: true"

Getting the notification delivery error networkError: true occurs when our notification engine fails to establish a successful network connection with your assigned callback URL.

Because this failure occurs during the network transport phase, it generally means the request was dropped, blocked, or rejected before it could reach or be processed by your web server application. As a result, you will often not see any incoming requests in your web server logs (e.g., IIS, Nginx, or Apache).

Example error:

"nextTime": 1672646494972,
"timestamp": 1672646502000,
"retryCount": 4,
"failed": true,
"response": {
     "networkError": true
 }

Common Causes

There are several network and infrastructure factors that can trigger this error:

1. SSL/TLS Certificate Verification: Our notification service may be unable to verify the SSL certificate of your domain. Ensure your certificate is valid, properly configured, and issued by a trusted Certificate Authority.
2. Cloud & Perimeter Firewalls: Even if local operating system firewalls (like Windows Firewall or iptables) are disabled, hosting providers (e.g., AWS Security Groups, Azure NSGs, Hetzner, or OVH edge firewalls) often enforce external filtering. They may be dropping incoming traffic originating from Google Cloud Platform (GCP) IP ranges.
3. HTTP Traffic Interception: Unencrypted HTTP (port 80) callbacks are occasionally inspected, filtered, or silently dropped by intermediate network nodes or upstream ISPs.
4. Web Server Host Headers and Binding Rules: When webhooks are dispatched, the request includes explicit host headers (e.g., Host: yourdomain.com). If your web server (like IIS) or reverse proxy drops or resets requests that do not strictly match its binding rules, the connection will terminate before an HTTP request is logged.
5. DNS Resolution Bottlenecks: If your domain does not resolve consistently across standard public DNS resolvers, or if there are IPv6 / split-brain DNS rules involved, automated workers may fail to establish a connection.

Steps to Troubleshoot

1. Isolate the Issue Using a Public Testing Endpoint

To determine whether the issue originates from the Tatum notification engine or your network environment, temporarily update your callback URL in the Tatum Dashboard (or via REST API) to a public testing endpoint like Webhook.site.

• Trigger an event to see if the webhook arrives at the test URL.
• If Webhook.site successfully receives the alert, it confirms your Tatum subscription is fully functional and points to an ingestion, routing, or firewall hurdle on your server's end.

2. Whitelist Tatum IP Addresses

Ensure that Tatum’s notification infrastructure can reach your server. You must whitelist Tatum IPs on your ingestion environment and edge firewalls.

• Review the latest list of IPs here: Tatum IPs, WAF, and HMAC
• Tip: Verifying that your server can ping Tatum IPs confirms outbound connectivity, but you must ensure inbound POST requests from these IPs are explicitly allowed.

3. Upgrade to HTTPS

We strongly recommend configuring SSL/TLS and updating your callback URL to use https:// instead of http:// for better reliability and to prevent intermediate packet inspection from dropping the payloads.

4. Verify Server Bindings & Payload Format

• Check that your server bindings strictly accept the domain configured in your webhook URL.
• Webhooks are sent as standard POST requests with the header Content-Type: application/json. No special compression or custom encoding is used. Ensure your endpoint accepts these standard headers.
• Test your endpoint locally and externally using cURL or Postman to replicate the exact payload structure.

5. Secure with HMAC

To guarantee the authenticity of the notification and ensure it hasn't been tampered with, consider enabling HMAC. When HMAC is enabled for your API key, Tatum includes an x-payload-hash header (a Base64 HMAC SHA512 digest of the raw JSON body) that you can use to verify the sender.