Skip to main content

Overview

Webhooks allow you to receive real-time notifications when specific events occur in the Zochil API. Instead of polling our API for changes, webhooks push data to your application as events happen.

How Webhooks Work

  1. Configure: Set up webhook endpoints in your application
  2. Subscribe: Register your webhook URL for specific events
  3. Receive: Get instant notifications when events occur
  4. Process: Handle the webhook payload in your application

Webhook Events

User Events

Order Events

Product Events

Cart Events

Setting Up Webhooks

1. Create a Webhook Endpoint

Create an HTTP endpoint in your application to receive webhook notifications:

2. Register Your Webhook

Register your webhook endpoint using the Admin API:

Webhook Payload Structure

All webhook payloads follow this structure:

Payload Fields

Example Event Payloads

User Created Event

Order Created Event

Inventory Updated Event

Security

Signature Verification

All webhooks include an X-Zochil-Signature header for verification:

IP Whitelisting

Webhook requests come from these IP ranges:

Handling Failures

Retry Logic

If your webhook endpoint returns a non-2xx status code, we’ll retry:
  • Immediate retry: After 1 second
  • Exponential backoff: 5s, 25s, 125s, 300s
  • Maximum attempts: 5 retries
  • Timeout: 30 seconds per attempt

Failed Webhook Dashboard

Monitor failed webhooks in your admin dashboard:

Best Practices

1. Idempotency

Handle duplicate webhook deliveries gracefully:

2. Async Processing

Process webhooks asynchronously to respond quickly:

3. Error Handling

Log errors and return appropriate status codes:

Testing Webhooks

Local Development

Use tools like ngrok to expose your local server:

Webhook Testing Tool

Create a simple webhook tester:

Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Trigger a test webhook delivery:

Next Steps

Admin API

Learn about webhook management endpoints

Error Handling

Handle webhook errors gracefully