Delivery & Retries

Rules your receiver endpoint must follow and how Zertiban behaves when something fails.

This section defines how Zertiban delivers webhooks and the requirements the receiver endpoint must meet to guarantee a stable, consistent and resilient integration.

Zertiban implements an at-least-once delivery model: the same event may be sent more than once in retry scenarios or network failures. For this reason, deduplication on the receiver side is mandatory.

Receiver endpoint rules

The endpoint that receives webhooks must satisfy the following functional and technical requirements:

1. Signature verification. Every webhook must be validated using the HMAC-SHA256 mechanism described in Signature Verification. No event with an invalid signature should be processed.
2. Response time. The endpoint must respond 2xx in under 5 seconds. If processing takes longer, respond 200 OK immediately and continue processing asynchronously in the background.
3. Event deduplication. Use eventUuid as the idempotency key. Store processed events and discard them if received again to avoid duplicated side effects.
4. No redirects. The endpoint must not return 3xx responses. Zertiban does not follow redirects under any circumstances: any redirect can cause event loss.

Asynchronous processing recommended

If your business logic involves expensive operations or depends on external systems (ERP, DB, emails, queues…), apply the following pattern:

1. Verify the signature.
2. Persist the event in internal storage.
3. Respond 200 OK immediately.
4. Process the event asynchronously via a queue or worker.

This approach improves system resilience and avoids blocking the reception of new events.

Retry policy

Zertiban automatically retries webhook delivery when it does not receive a satisfactory response. The policy is defined as follows:

Parameter	Value
Total attempts	3
Interval between retries	0.5 seconds (fixed)
HTTP connection timeout	5 seconds
HTTP response timeout	5 seconds

Batch reprocessing

If all 3 attempts fail, undelivered events are retried via an internal batch process roughly every 1 minute. This mechanism ensures high delivery availability even in case of temporary failures on the receiver endpoint.

Troubleshooting: I don't receive notifications

If webhooks are not arriving correctly, verify the following:

1. Endpoint registration. Confirm with Zertiban that the URL is correctly registered, active and associated with the correct businessUuid.
2. External reachability. The endpoint must be publicly reachable via HTTPS. For external testing you can use tools like reqbin.com or any HTTP client outside your internal network.
3. Endpoint response. The endpoint must respond only with 2xx codes, in under 5 seconds. 3xx, 4xx or 5xx responses can trigger retries or event loss.
4. Local development. For local environments, expose the endpoint via HTTPS tunnels, for example with ngrok (ngrok http 3000). The generated public URL can be used as a temporary endpoint in sandbox.
5. Signature validation. During the initial integration phase, accept all webhooks without blocking, log zb-signature and zb-timestamp, and validate the signature calculation afterwards. This makes it easier to spot discrepancies in your algorithm implementation.

Debug shortcut

Always log eventUuid, eventType, zb-timestamp and the signature verification result. This approach simplifies incident diagnosis and significantly reduces integration time.

Final recommendation

A well-designed webhook consumer should prioritize:

• Idempotency.
• Low response latency.
• Asynchronous processing.
• Tolerance to retries.

This guarantees a robust, scalable integration that is consistent with Zertiban's delivery model.