Skip to main content

Webhook Retries and Error Handling

OpenTiendas automatically retries webhook deliveries up to 5 times if the initial attempt fails, ensuring reliable delivery of critical event notifications.

Retry Schedule​

AttemptTiming
1Immediate (after 10 seconds)
2After 2 minutes
3After 10 minutes
4After 1 hour
5After 10 hours

Each webhook delivery has a maximum response time of 5 seconds. If your endpoint fails to respond within this time or returns an HTTP status code other than 2xx, the system will schedule the next retry. If all retry attempts fail, OpenTiendas will stop retries and mark the delivery as failed. Each retry delivers the same event payload, including the same event_id, type, and data.

Security Considerations​

For every webhook attempt, including retries:

  • Validate the digital signature included in the X-Signature header to ensure authenticity.
  • Use the HMAC SHA256 validation process described in the Security Guide.

Idempotency​

  • Design your webhook handlers to be idempotent—processing the same event multiple times should not cause duplicate actions.
  • Use unique identifiers such as event_id from the payload to check if an event has already been processed.
  • Store processing results (e.g., in a database or cache) to identify and skip already handled events.

Best Practices for Reliable Handling​

  • Return an HTTP 2xx status (e.g., 200 OK) to confirm successful processing.
  • Return appropriate 4xx/5xx codes for failures, and log errors for analysis.
  • Employ asynchronous processing to acknowledge requests quickly and handle processing in the background.
  • Make your webhook endpoint highly available and fast to respond to minimize retries.
  • Set up logging and monitoring to track webhook deliveries, retries, and failures.
  • Test your webhook endpoint regularly with sample payloads to ensure it handles retries and errors gracefully.

Scaling Considerations​

  • Design your system to handle high webhook traffic, especially during peak events like sales or product launches.
  • Use message queues, serverless functions, or background jobs to offload processing and ensure high availability.
  • Employ rate limiting and load balancing to maintain performance under heavy load.

Stay proactive in handling webhooks to keep your integrations seamless and reliable.