ZezoPay Webhook Documentation

Complete guide to all ZezoPay webhook events and data structures

ByZezoPay Team

Last updated:February 03, 2025

Overview

When you use ZezoPay to collect payments, ZezoPay automatically sends HTTP POST requests to your configured webhook URL. This document lists all the events and data that ZezoPay sends to your webhook.

Events Summary

Total Events: 25

Payment Events: 9
Subscription Events: 7
Digital Product Purchase Events: 8

Webhook Request Format

Every webhook request follows this structure:

{
  "data": {
    "entity": "event",
    "account_id": "merchant-account-id",
    "event": "event.name",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "entity-id",
          "entity": "payment",
          "created_at": 1234567890000,
          "status": "paid"
        }
      }
    }
  }
}

Important Timestamps

created_at in main data: Unix timestamp in seconds - created_at in entity data: Unix timestamp in milliseconds - The payload key depends on entity type: payment, subscription, or digital_product

Request Headers

Every webhook request includes:

Header Name	Description
`Content-Type`	`application/json`
`x-zezopay-request-id`	Unique request ID
`x-zezopay-webhook-signature`	HMAC SHA256 signature (if secret is configured)

Common Entity Fields

All entities share these common fields:

Payment & Subscription Fields

id - Entity ID
entity - Entity type ("payment", "subscription", or "digital_product")
created_at - Timestamp in milliseconds
price - Amount
status - Current status
order_id - Order ID
pw_id - Payment gateway ID
payment_gateway - Gateway name (razorpay, stripe, phonepe, ccavenue)
user_id - User ID
user_name - User name
user_email - User email
user_phone - User phone number
meta_data - Additional metadata

Payment Events

payment.created

Triggered when a payment is created.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.created",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "created",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

payment.paid

Triggered when payment is successfully completed.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.paid",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "paid",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

payment.failed

Triggered when payment fails.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.failed",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "failed",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

payment.attempted

Triggered when a payment attempt is made.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.attempted",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "attempted",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

payment.cancelled

Triggered when payment is cancelled.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.cancelled",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "cancelled",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

payment.authorized

Triggered when payment is authorized.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.authorized",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "authorized",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

payment.refunded

Triggered when payment is refunded.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.refunded",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "refunded",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

payment.chargeback

Triggered when a chargeback occurs.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.chargeback",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "chargeback",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

payment.pending

Triggered when payment is pending.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439011",
    "event": "payment.pending",
    "contains": ["payment"],
    "created_at": 1234567890,
    "payload": {
      "payment": {
        "entity": {
          "id": "pay_123456",
          "entity": "payment",
          "created_at": 1234567890000,
          "price": 1000,
          "currency": "INR",
          "status": "pending",
          "order_id": "order_789",
          "pw_id": "pay_razorpay_123",
          "payment_gateway": "razorpay",
          "user_id": "user_456",
          "user_name": "John Doe",
          "user_email": "john@example.com",
          "user_phone": "+1234567890",
          "meta_data": {}
        }
      }
    }
  }
}

Subscription Events

subscription.active

Triggered when subscription becomes active.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439012",
    "event": "subscription.active",
    "contains": ["subscription"],
    "created_at": 1234567890,
    "payload": {
      "subscription": {
        "entity": {
          "id": "sub_123456",
          "entity": "subscription",
          "created_at": 1234567890000,
          "plan_id": "plan_789",
          "plan_name": "Premium Plan",
          "plan_duration": 30,
          "plan_duration_unit": "days",
          "plan_price": 999,
          "price": 999,
          "payment_id": "pay_123",
          "status": "active",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Jane Smith",
          "user_email": "jane@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "start_date": 1234567890000,
          "end_date": 1237248000000,
          "meta_data": {}
        }
      }
    }
  }
}

subscription.trial

Triggered when subscription enters trial period.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439012",
    "event": "subscription.trial",
    "contains": ["subscription"],
    "created_at": 1234567890,
    "payload": {
      "subscription": {
        "entity": {
          "id": "sub_123456",
          "entity": "subscription",
          "created_at": 1234567890000,
          "plan_id": "plan_789",
          "plan_name": "Premium Plan",
          "plan_duration": 30,
          "plan_duration_unit": "days",
          "plan_price": 999,
          "price": 0,
          "payment_id": "pay_123",
          "status": "trial",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Jane Smith",
          "user_email": "jane@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "start_date": 1234567890000,
          "end_date": 1237248000000,
          "meta_data": {}
        }
      }
    }
  }
}

subscription.expired

Triggered when subscription expires.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439012",
    "event": "subscription.expired",
    "contains": ["subscription"],
    "created_at": 1234567890,
    "payload": {
      "subscription": {
        "entity": {
          "id": "sub_123456",
          "entity": "subscription",
          "created_at": 1234567890000,
          "plan_id": "plan_789",
          "plan_name": "Premium Plan",
          "plan_duration": 30,
          "plan_duration_unit": "days",
          "plan_price": 999,
          "price": 999,
          "payment_id": "pay_123",
          "status": "expired",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Jane Smith",
          "user_email": "jane@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "start_date": 1234567890000,
          "end_date": 1237248000000,
          "meta_data": {}
        }
      }
    }
  }
}

subscription.failed

Triggered when subscription payment fails.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439012",
    "event": "subscription.failed",
    "contains": ["subscription"],
    "created_at": 1234567890,
    "payload": {
      "subscription": {
        "entity": {
          "id": "sub_123456",
          "entity": "subscription",
          "created_at": 1234567890000,
          "plan_id": "plan_789",
          "plan_name": "Premium Plan",
          "plan_duration": 30,
          "plan_duration_unit": "days",
          "plan_price": 999,
          "price": 999,
          "payment_id": "pay_123",
          "status": "failed",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Jane Smith",
          "user_email": "jane@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "start_date": 1234567890000,
          "end_date": 1237248000000,
          "meta_data": {}
        }
      }
    }
  }
}

subscription.canceled

Triggered when subscription is cancelled.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439012",
    "event": "subscription.canceled",
    "contains": ["subscription"],
    "created_at": 1234567890,
    "payload": {
      "subscription": {
        "entity": {
          "id": "sub_123456",
          "entity": "subscription",
          "created_at": 1234567890000,
          "plan_id": "plan_789",
          "plan_name": "Premium Plan",
          "plan_duration": 30,
          "plan_duration_unit": "days",
          "plan_price": 999,
          "price": 999,
          "payment_id": "pay_123",
          "status": "canceled",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Jane Smith",
          "user_email": "jane@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "start_date": 1234567890000,
          "end_date": 1237248000000,
          "meta_data": {}
        }
      }
    }
  }
}

subscription.inactive

Triggered when subscription becomes inactive.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439012",
    "event": "subscription.inactive",
    "contains": ["subscription"],
    "created_at": 1234567890,
    "payload": {
      "subscription": {
        "entity": {
          "id": "sub_123456",
          "entity": "subscription",
          "created_at": 1234567890000,
          "plan_id": "plan_789",
          "plan_name": "Premium Plan",
          "plan_duration": 30,
          "plan_duration_unit": "days",
          "plan_price": 999,
          "price": 999,
          "payment_id": "pay_123",
          "status": "inactive",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Jane Smith",
          "user_email": "jane@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "start_date": 1234567890000,
          "end_date": 1237248000000,
          "meta_data": {}
        }
      }
    }
  }
}

subscription.pending

Triggered when subscription is pending.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439012",
    "event": "subscription.pending",
    "contains": ["subscription"],
    "created_at": 1234567890,
    "payload": {
      "subscription": {
        "entity": {
          "id": "sub_123456",
          "entity": "subscription",
          "created_at": 1234567890000,
          "plan_id": "plan_789",
          "plan_name": "Premium Plan",
          "plan_duration": 30,
          "plan_duration_unit": "days",
          "plan_price": 999,
          "price": 999,
          "payment_id": "pay_123",
          "status": "pending",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Jane Smith",
          "user_email": "jane@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "start_date": 1234567890000,
          "end_date": 1237248000000,
          "meta_data": {}
        }
      }
    }
  }
}

Digital Product Purchase Events

product.purchase.paid

Triggered when digital product purchase payment is completed.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439013",
    "event": "product.purchase.paid",
    "contains": ["digital_product"],
    "created_at": 1234567890,
    "payload": {
      "digital_product": {
        "entity": {
          "id": "prod_123456",
          "entity": "digital_product",
          "created_at": 1234567890000,
          "product_id": "product_789",
          "product_name": "Digital Course",
          "product_price": 499,
          "price": 499,
          "currency": "INR",
          "product_expiry": "365",
          "product_expiry_unit": "days",
          "product_slug": "digital-course",
          "product_description": "Learn digital marketing",
          "product_category": "Education",
          "product_purchase_id": "prod_123456",
          "status": "active",
          "payment_id": "pay_123",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Bob Johnson",
          "user_email": "bob@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "meta_data": {}
        }
      }
    }
  }
}

product.purchase.pending

Triggered when digital product purchase is pending.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439013",
    "event": "product.purchase.pending",
    "contains": ["digital_product"],
    "created_at": 1234567890,
    "payload": {
      "digital_product": {
        "entity": {
          "id": "prod_123456",
          "entity": "digital_product",
          "created_at": 1234567890000,
          "product_id": "product_789",
          "product_name": "Digital Course",
          "product_price": 499,
          "price": 499,
          "currency": "INR",
          "product_expiry": "365",
          "product_expiry_unit": "days",
          "product_slug": "digital-course",
          "product_description": "Learn digital marketing",
          "product_category": "Education",
          "product_purchase_id": "prod_123456",
          "status": "pending",
          "payment_id": "pay_123",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Bob Johnson",
          "user_email": "bob@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "meta_data": {}
        }
      }
    }
  }
}

product.purchase.failed

Triggered when digital product purchase payment fails.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439013",
    "event": "product.purchase.failed",
    "contains": ["digital_product"],
    "created_at": 1234567890,
    "payload": {
      "digital_product": {
        "entity": {
          "id": "prod_123456",
          "entity": "digital_product",
          "created_at": 1234567890000,
          "product_id": "product_789",
          "product_name": "Digital Course",
          "product_price": 499,
          "price": 499,
          "currency": "INR",
          "product_expiry": "365",
          "product_expiry_unit": "days",
          "product_slug": "digital-course",
          "product_description": "Learn digital marketing",
          "product_category": "Education",
          "product_purchase_id": "prod_123456",
          "status": "failed",
          "payment_id": "pay_123",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Bob Johnson",
          "user_email": "bob@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "meta_data": {}
        }
      }
    }
  }
}

product.purchase.cancelled

Triggered when digital product purchase is cancelled.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439013",
    "event": "product.purchase.cancelled",
    "contains": ["digital_product"],
    "created_at": 1234567890,
    "payload": {
      "digital_product": {
        "entity": {
          "id": "prod_123456",
          "entity": "digital_product",
          "created_at": 1234567890000,
          "product_id": "product_789",
          "product_name": "Digital Course",
          "product_price": 499,
          "price": 499,
          "currency": "INR",
          "product_expiry": "365",
          "product_expiry_unit": "days",
          "product_slug": "digital-course",
          "product_description": "Learn digital marketing",
          "product_category": "Education",
          "product_purchase_id": "prod_123456",
          "status": "cancelled",
          "payment_id": "pay_123",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Bob Johnson",
          "user_email": "bob@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "meta_data": {}
        }
      }
    }
  }
}

product.purchase.active

Triggered when digital product purchase is active.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439013",
    "event": "product.purchase.active",
    "contains": ["digital_product"],
    "created_at": 1234567890,
    "payload": {
      "digital_product": {
        "entity": {
          "id": "prod_123456",
          "entity": "digital_product",
          "created_at": 1234567890000,
          "product_id": "product_789",
          "product_name": "Digital Course",
          "product_price": 499,
          "price": 499,
          "currency": "INR",
          "product_expiry": "365",
          "product_expiry_unit": "days",
          "product_slug": "digital-course",
          "product_description": "Learn digital marketing",
          "product_category": "Education",
          "product_purchase_id": "prod_123456",
          "status": "active",
          "payment_id": "pay_123",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Bob Johnson",
          "user_email": "bob@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "meta_data": {}
        }
      }
    }
  }
}

product.purchase.trial

Triggered when digital product purchase is in trial.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439013",
    "event": "product.purchase.trial",
    "contains": ["digital_product"],
    "created_at": 1234567890,
    "payload": {
      "digital_product": {
        "entity": {
          "id": "prod_123456",
          "entity": "digital_product",
          "created_at": 1234567890000,
          "product_id": "product_789",
          "product_name": "Digital Course",
          "product_price": 499,
          "price": 0,
          "currency": "INR",
          "product_expiry": "365",
          "product_expiry_unit": "days",
          "product_slug": "digital-course",
          "product_description": "Learn digital marketing",
          "product_category": "Education",
          "product_purchase_id": "prod_123456",
          "status": "trial",
          "payment_id": "pay_123",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Bob Johnson",
          "user_email": "bob@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "meta_data": {}
        }
      }
    }
  }
}

product.purchase.inactive

Triggered when digital product purchase becomes inactive.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439013",
    "event": "product.purchase.inactive",
    "contains": ["digital_product"],
    "created_at": 1234567890,
    "payload": {
      "digital_product": {
        "entity": {
          "id": "prod_123456",
          "entity": "digital_product",
          "created_at": 1234567890000,
          "product_id": "product_789",
          "product_name": "Digital Course",
          "product_price": 499,
          "price": 499,
          "currency": "INR",
          "product_expiry": "365",
          "product_expiry_unit": "days",
          "product_slug": "digital-course",
          "product_description": "Learn digital marketing",
          "product_category": "Education",
          "product_purchase_id": "prod_123456",
          "status": "inactive",
          "payment_id": "pay_123",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Bob Johnson",
          "user_email": "bob@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "meta_data": {}
        }
      }
    }
  }
}

product.purchase.expired

Triggered when digital product purchase expires.

{
  "data": {
    "entity": "event",
    "account_id": "507f1f77bcf86cd799439013",
    "event": "product.purchase.expired",
    "contains": ["digital_product"],
    "created_at": 1234567890,
    "payload": {
      "digital_product": {
        "entity": {
          "id": "prod_123456",
          "entity": "digital_product",
          "created_at": 1234567890000,
          "product_id": "product_789",
          "product_name": "Digital Course",
          "product_price": 499,
          "price": 499,
          "currency": "INR",
          "product_expiry": "365",
          "product_expiry_unit": "days",
          "product_slug": "digital-course",
          "product_description": "Learn digital marketing",
          "product_category": "Education",
          "product_purchase_id": "prod_123456",
          "status": "expired",
          "payment_id": "pay_123",
          "order_id": "order_456",
          "payment_gateway": "razorpay",
          "user_id": "user_789",
          "user_name": "Bob Johnson",
          "user_email": "bob@example.com",
          "user_phone": "+1234567890",
          "pw_id": "payment-widget-id",
          "meta_data": {}
        }
      }
    }
  }
}

Implementation Guide

How Webhooks Work

Configure your webhook URL in ZezoPay dashboard
Event occurs (payment, subscription, or product purchase)
ZezoPay sends POST request to your webhook URL
Your server receives and processes the data
Respond with 200 OK status code

Best Practices

Response Requirements

Always respond with 200 OK status code within 10 seconds to mark webhook as successful.

Respond Quickly - Process asynchronously, respond immediately with 200 OK
Retry Handling - ZezoPay automatically retries failed webhooks:
- 1st retry: After 5 minutes
- 2nd retry: After 30 minutes
- 3rd retry: After 2 hours
Signature Verification - Always verify webhook signatures for security
Idempotency - Handle duplicate webhook deliveries gracefully

Signature Verification

Node.js Example

const crypto = require("crypto");
 
function verifyWebhookSignature(requestBody, signature, secret) {
  if (!secret) return true; // Skip if no secret configured
 
  const computedSignature = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify({ data: requestBody }))
    .digest("hex");
 
  return computedSignature === signature;
}
 
app.post("/api/webhooks/zezopay", express.json(), (req, res) => {
  const signature = req.headers["x-zezopay-webhook-signature"];
  const webhookSecret = process.env.ZEZOPAY_WEBHOOK_SECRET;
 
  // Verify signature
  if (!verifyWebhookSignature(req.body, signature, webhookSecret)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
 
  const event = req.body;
  const eventType = event.data?.event;
 
  // Process webhook based on event type
  switch (eventType) {
    case "payment.paid":
      // Handle payment.paid
      console.log("Payment completed:", event.data.payload.payment);
      break;
    case "payment.failed":
      // Handle payment.failed
      break;
    case "subscription.active":
      // Handle subscription.active
      break;
    case "product.purchase.paid":
      // Handle product.purchase.paid
      break;
    // Handle all other events...
  }
 
  // Always respond with 200 OK
  res.status(200).json({ received: true });
});

Security Notice

Always verify webhook signatures in production to ensure requests are coming from ZezoPay and haven't been tampered with.

Support

For questions or support, please contact the ZezoPay support team.