Webhook Troubleshooting

If you need to quickly locate the cause based on the error phenomenon, you can also directly check the Webhook delivery failure.

Connection timeout

Check:

Whether the target domain name can be accessed from the public network.
Whether the server returns a response within the specified time.
Whether the request is blocked by a firewall, security group, or WAF.
Whether DNS can be resolved stably.
Whether the service timed out due to a cold start or a slow database connection.

Check target domain name resolution, certificate validity, certificate chain, and TLS configuration. Do not use local addresses, test intranet addresses, or addresses only accessible from the corporate network as production targets.

3xx, 4xx or 5xx

3xx: Check whether jump is configured. It is recommended to use the final HTTPS address directly.
4xx: Check routing, token, request method and server permissions.
5xx: Check the target service error log and Response Body to confirm application exceptions or dependent service failures.

The Webhook receiving interface should complete the verification and return the results as soon as possible. Business processing that takes a long time can be put into an asynchronous queue.

Token verification failed

Check:

Whether the console Token is consistent with the server configuration.
Whether the Authorization request header parsing method is correct.
Whether the Public API Key is mistaken for the Bearer Token.
Whether the Token has been updated but the server still uses the old value.
Are there multiple environments using different configurations.

Do not return the full token or internal verification details in error responses.

Repeating events

Use Delivery ID or Request ID as idempotent key. When the same ID is received repeatedly, success is returned and repeated business actions are skipped. In particular, non-repeatable operations such as issuing coupons, deducting money, and modifying account status must be uniquely constrained or checked at the database layer.

Retry and delivery order

The current version does not automatically retry failed deliveries, nor does it guarantee strict delivery order across events. Your server should:

Allow repeated arrivals of the same event.
Does not rely on events arriving in strict order of occurrence.
Use event time and business status to determine whether it can be processed.
Record the Request ID and Delivery ID for payloads that cannot be processed.
Confirm final status via delivery log.

If you need to compensate for a failure event, please save the Delivery ID, Request ID and processing status on your server, and then initiate compensation or manual replay based on business rules. The current version of Geelab does not automatically put failed tasks back into the queue.

When HTTP will not be initiated

The following situations will fail before the platform makes the request, so your target URL will not receive the request:

The destination address resolves to a restricted address, or the URL does not comply with security rules.
The platform is temporarily unable to read the event content required for this delivery.
The webhook data cannot be parsed, the version is not supported, or necessary content is missing.

Such results will display the corresponding failure status in the delivery log. If no result details are available in the logs, please also record the logs of the local receiving service and provide the Delivery ID or Request ID to contact support.