Reliability & Retries - RMZ Developer Docs

RMZ uses Spatie Webhook Server under the hood for reliable webhook delivery. This page covers the retry strategy, timeouts, and how delivery status is tracked.

Timeout

Each webhook delivery attempt has a 3-second timeout. If your server does not respond within 3 seconds, the attempt is marked as failed and may be retried.

Return a 200 response immediately and process the webhook payload asynchronously (e.g., in a background job). This prevents timeouts for heavy processing.

Retry Strategy

Failed deliveries are retried using an exponential backoff strategy. The delay between attempts increases exponentially:

Attempt	Approximate Delay
1st retry	~10 seconds
2nd retry	~100 seconds
3rd retry	~1,000 seconds (~17 min)
4th retry	~10,000 seconds (~2.8 hrs)

Configurable Retries

When creating a webhook, you choose the maximum number of tries (1 to 5):

Tries Setting	Behavior
1	Single attempt, no retries
2	1 initial attempt + 1 retry
3	1 initial attempt + 2 retries
4	1 initial attempt + 3 retries
5	1 initial attempt + 4 retries

The tries setting includes the initial attempt. Setting tries to 3 means 1 initial attempt and 2 retries for a total of 3 delivery attempts.

Success Criteria

A delivery is considered successful when your server responds with any 2xx HTTP status code (200, 201, 202, etc.). A delivery is considered failed when:

Your server responds with a non-2xx status code (4xx, 5xx)
The connection times out (exceeds 3 seconds)
The connection is refused or DNS resolution fails

Delivery Logging

Every webhook delivery attempt is logged with the following information:

Field	Description
`uri`	The destination URL
`payload`	The webhook payload (encrypted at rest)
`status_code`	HTTP response status code (0 if no response received)
`response`	Response body from your server
`headers`	Response headers
`is_pending`	`true` while delivery is in progress
`is_error`	`true` if the final attempt failed

Webhook payloads are encrypted at rest in the database for security. The X-RMZ-REQUEST-ID header value corresponds to the log entry ID.

Automatic Disabling of Failing Webhooks

RMZ periodically evaluates webhook delivery history and automatically disables webhooks that are consistently failing. The default criteria are:

Parameter	Default	Description
Failure rate threshold	80%	Webhooks with a failure rate at or above this percentage are disabled
Minimum requests	5	A webhook must have at least this many delivery attempts before it can be evaluated
Lookback period	3 months	Only delivery attempts within this window are considered

A delivery is counted as failed if is_error is true or the response status code is outside the 2xx range. When a webhook is disabled, the store owner can re-enable it from the dashboard after fixing the endpoint issue.

SSL Verification

By default, RMZ verifies the SSL certificate of your webhook endpoint. Self-signed certificates or invalid certificates will cause delivery to fail.

Always use HTTPS for your webhook endpoints. While the webhook will attempt delivery to HTTP URLs, sensitive order data (including customer details and digital codes) is included in the payload.

Idempotency

Webhooks may be delivered more than once due to retries or network issues. Design your webhook handler to be idempotent — processing the same event twice should produce the same result. Use the X-RMZ-REQUEST-ID header to detect duplicate deliveries:

const processedRequests = new Set();

app.post("/webhooks/rmz", (req, res) => {
  const requestId = req.headers["x-rmz-request-id"];

  if (processedRequests.has(requestId)) {
    // Already processed, return success to prevent further retries
    return res.status(200).json({ received: true, duplicate: true });
  }

  // Process the webhook...
  processedRequests.add(requestId);

  res.status(200).json({ received: true });
});

In production, store processed request IDs in a database or Redis rather than in-memory. Use a TTL of 7 days to automatically clean up old entries.

Best Practices

Respond quickly. Return 200 immediately and process asynchronously. Do not perform slow operations (API calls, database writes, email sending) before responding.
Handle retries. Use the X-RMZ-REQUEST-ID header for deduplication. Store processed IDs to avoid duplicate processing.
Use HTTPS. Protect sensitive customer and order data in transit.
Verify signatures. When signing is enabled, always verify the signature before processing the payload.
Set appropriate retry counts. Use higher retry counts (3-5) for critical integrations and lower counts (1-2) for non-critical notifications.
Monitor delivery status. Check the webhook logs in your dashboard to identify persistent failures. Fix endpoint issues promptly to avoid missing events.
Handle all status codes. If your server returns a non-2xx status intentionally (e.g., 422 for an invalid payload), be aware that RMZ will retry the delivery.

​Timeout

​Retry Strategy

​Configurable Retries

​Success Criteria

​Delivery Logging

​Automatic Disabling of Failing Webhooks

​SSL Verification

​Idempotency

​Best Practices

Timeout

Retry Strategy

Configurable Retries

Success Criteria

Delivery Logging

Automatic Disabling of Failing Webhooks

SSL Verification

Idempotency

Best Practices