Webhooks

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

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

Webhook Events

User Events

Event	Description
`user.created`	New user registration
`user.updated`	User profile changes
`user.deleted`	User account deletion
`user.verified`	Email verification completed

Order Events

Event	Description
`order.created`	New order placed
`order.updated`	Order status changed
`order.cancelled`	Order cancelled
`order.completed`	Order fulfilled
`order.payment_succeeded`	Payment processed successfully
`order.payment_failed`	Payment processing failed

Product Events

Event	Description
`product.created`	New product added
`product.updated`	Product information changed
`product.deleted`	Product removed
`inventory.updated`	Product inventory changed

Cart Events

Event	Description
`cart.item_added`	Item added to cart
`cart.item_removed`	Item removed from cart
`cart.abandoned`	Cart abandoned (no activity for 24h)

Setting Up Webhooks

1. Create a Webhook Endpoint

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

const express = require("express");
const crypto = require("crypto");
const app = express();

app.use(express.json());

app.post("/webhooks/zochil", (req, res) => {
  const signature = req.get("X-Zochil-Signature");
  const payload = JSON.stringify(req.body);

  // Verify webhook signature (recommended)
  if (!verifySignature(payload, signature)) {
    return res.status(401).send("Unauthorized");
  }

  const { event, data } = req.body;

  // Handle the event
  switch (event) {
    case "user.created":
      console.log("New user:", data.user);
      // Send welcome email, create user profile, etc.
      break;

    case "order.created":
      console.log("New order:", data.order);
      // Update inventory, send confirmation, etc.
      break;

    default:
      console.log("Unhandled event:", event);
  }

  res.status(200).send("OK");
});

function verifySignature(payload, signature) {
  const webhookSecret = process.env.ZOCHIL_WEBHOOK_SECRET;
  const expectedSignature = crypto
    .createHmac("sha256", webhookSecret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

app.listen(3000);

2. Register Your Webhook

curl -X POST "https://api.zochil.io/admin/webhooks" \
  -H "access-token: YOUR_ACCESS_TOKEN" \
  -H "device-id: YOUR_DEVICE_ID" \
  -H "merchant-id: YOUR_MERCHANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/zochil",
    "events": ["user.created", "order.created", "order.updated"],
    "active": true,
    "secret": "your-webhook-secret-key"
  }'

Webhook Payload Structure

All webhook payloads follow this structure:

{
  "id": "evt_1234567890abcdef",
  "event": "user.created",
  "created": 1640995200,
  "data": {
    "user": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "user@example.com",
      "name": "John Doe",
      "created_at": "2023-01-01T00:00:00Z"
    }
  },
  "api_version": "v1"
}

Payload Fields

Example Event Payloads

User Created Event

{
  "id": "evt_user_created_123",
  "event": "user.created",
  "created": 1640995200,
  "data": {
    "user": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "user@example.com",
      "name": "John Doe",
      "phone": "+1234567890",
      "is_verified": false,
      "created_at": "2023-01-01T00:00:00Z"
    }
  },
  "api_version": "v1"
}

Order Created Event

{
  "id": "evt_order_created_456",
  "event": "order.created",
  "created": 1640995200,
  "data": {
    "order": {
      "id": "order_123e4567e89b12d3",
      "order_number": "ORD-2023-001",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "pending",
      "total": 299.99,
      "currency": "USD",
      "items": [
        {
          "product_id": "prod_123",
          "quantity": 2,
          "price": 149.99
        }
      ],
      "created_at": "2023-01-01T00:00:00Z"
    }
  },
  "api_version": "v1"
}

Inventory Updated Event

{
  "id": "evt_inventory_updated_789",
  "event": "inventory.updated",
  "created": 1640995200,
  "data": {
    "product": {
      "id": "prod_123e4567e89b12d3",
      "sku": "PWH-001",
      "name": "Premium Wireless Headphones"
    },
    "inventory": {
      "previous_quantity": 100,
      "current_quantity": 95,
      "reserved": 5,
      "available": 90
    }
  },
  "api_version": "v1"
}

Security

Signature Verification

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

const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  const receivedSignature = signature.replace("sha256=", "");

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature)
  );
}

IP Whitelisting

Webhook requests come from these IP ranges:

198.51.100.0/24
203.0.113.0/24

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:

GET /admin/webhooks/{webhook_id}/deliveries

Best Practices

1. Idempotency

Handle duplicate webhook deliveries gracefully:

const processedEvents = new Set();

app.post("/webhooks/zochil", (req, res) => {
  const eventId = req.body.id;

  // Check if we've already processed this event
  if (processedEvents.has(eventId)) {
    return res.status(200).send("Already processed");
  }

  // Process the event
  handleEvent(req.body);

  // Mark as processed
  processedEvents.add(eventId);

  res.status(200).send("OK");
});

2. Async Processing

Process webhooks asynchronously to respond quickly:

const Queue = require("bull");
const webhookQueue = new Queue("webhook processing");

app.post("/webhooks/zochil", (req, res) => {
  // Add to queue for async processing
  webhookQueue.add("process-webhook", req.body);

  // Respond immediately
  res.status(200).send("OK");
});

webhookQueue.process("process-webhook", (job) => {
  const { event, data } = job.data;
  // Process the webhook data
  return handleWebhookEvent(event, data);
});

3. Error Handling

Log errors and return appropriate status codes:

app.post("/webhooks/zochil", async (req, res) => {
  try {
    await processWebhook(req.body);
    res.status(200).send("OK");
  } catch (error) {
    console.error("Webhook processing failed:", error);

    // Return 5xx for temporary failures (will be retried)
    if (error.temporary) {
      return res.status(503).send("Temporary failure");
    }

    // Return 4xx for permanent failures (won't be retried)
    res.status(400).send("Invalid webhook data");
  }
});

Testing Webhooks

Local Development

Use tools like ngrok to expose your local server:

# Install ngrok
npm install -g ngrok

# Expose your local server
ngrok http 3000

# Use the HTTPS URL for webhook registration
# https://abc123.ngrok.io/webhooks/zochil

Webhook Testing Tool

Create a simple webhook tester:

const express = require("express");
const app = express();

app.use(express.json());

app.post("/test-webhook", (req, res) => {
  console.log("Received webhook:");
  console.log("Headers:", req.headers);
  console.log("Body:", JSON.stringify(req.body, null, 2));

  res.status(200).send("Webhook received");
});

app.listen(3000, () => {
  console.log("Webhook tester running on port 3000");
});

Managing Webhooks

List Webhooks

GET /admin/webhooks

Update Webhook

PATCH /admin/webhooks/{webhook_id}

Delete Webhook

DELETE /admin/webhooks/{webhook_id}

Test Webhook

Trigger a test webhook delivery:

POST /admin/webhooks/{webhook_id}/test

Overview

How Webhooks Work

Webhook Events

User Events

Order Events

Product Events

Cart Events

Setting Up Webhooks

1. Create a Webhook Endpoint

2. Register Your Webhook

Webhook Payload Structure

Payload Fields

Example Event Payloads

User Created Event

Order Created Event

Inventory Updated Event

Security

Signature Verification

IP Whitelisting

Handling Failures

Retry Logic

Failed Webhook Dashboard

Best Practices

1. Idempotency

2. Async Processing

3. Error Handling

Testing Webhooks

Local Development

Webhook Testing Tool

Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Next Steps

Admin API

Error Handling

​Overview

​How Webhooks Work

​Webhook Events

​User Events

​Order Events

​Product Events

​Cart Events

​Setting Up Webhooks

​1. Create a Webhook Endpoint

​2. Register Your Webhook

​Webhook Payload Structure

​Payload Fields

​Example Event Payloads

​User Created Event

​Order Created Event

​Inventory Updated Event

​Security

​Signature Verification

​IP Whitelisting

​Handling Failures

​Retry Logic

​Failed Webhook Dashboard

​Best Practices

​1. Idempotency

​2. Async Processing

​3. Error Handling

​Testing Webhooks

​Local Development

​Webhook Testing Tool

​Managing Webhooks

​List Webhooks

​Update Webhook

​Delete Webhook

​Test Webhook

​Next Steps

Admin API

Error Handling

Overview

How Webhooks Work

Webhook Events

User Events

Order Events

Product Events

Cart Events

Setting Up Webhooks

1. Create a Webhook Endpoint

2. Register Your Webhook

Webhook Payload Structure

Payload Fields

Example Event Payloads

User Created Event

Order Created Event

Inventory Updated Event

Security

Signature Verification

IP Whitelisting

Handling Failures

Retry Logic

Failed Webhook Dashboard

Best Practices

1. Idempotency

2. Async Processing

3. Error Handling

Testing Webhooks

Local Development

Webhook Testing Tool

Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Next Steps