Zid Docs
Webhooks
Overview
Webhooks allow you to receive real-time data updates for various events. These events can range from order creation to customer login activities. This page serves as a comprehensive guide to understanding the supported webhook events, their payloads, and any conditions that can be applied to them.
:::info[]
Currency Handling for Orders
When the store currency, order currency, and the currency of the shipping address (for cash on delivery) are different, partners must convert the order total to the appropriate currency. The order details already provide both the currency type and the conversion rate, making it easy to apply the conversion when necessary. This ensures that the correct amount is processed smoothly, even when multiple currencies are involved.
:::
How to Subscribe
To subscribe to these webhook events, follow these steps:
Choose the event(s) you would like to subscribe to from the list of Supported Webhook Events below.
(Optional) If the event supports
conditions, check out the Event Conditions section to learn how to populate theconditionsfield.Use the Merchant API to make a request to the Create a Webhook endpoint (Link to API documentation).
In case you require an event or a condition that is not yet supported, please send your suggestion to the Zid App Market Support.
Subscription Events
The table below lists the subscription events, along with their descriptions. Each event sends a notification based on specific subscription activities.
| Event Name | Description |
|---|---|
app.market.subscription.active |
send notification on successful activation of subscription |
app.market.subscription.warning |
send notification 3 days before the last subscription date (T is the duration of the plan in days) |
app.market.subscription.suspended |
send notification on completion of subscription |
app.market.subscription.expired |
send notification on T+5 days of subscription where 5 days are GRACE Period and T is in the duration of the plan in days |
app.market.subscription.renew |
send notification on successful renewal of the same plan subscription 5 days before the last date |
app.market.subscription.upgrade |
Send notification on upgrade of subscription |
app.market.subscription.refunded |
send notification on refund of subscription |
app.market.application.install |
send notification on the installation of application |
app.market.application.uninstall |
send notification on uninstallation of the application |
Sample Webhook Request
In an attempt to Make it easy to integrate with the partner's system, we have made a generic request data for all the webhook events. All the webhook events share the same request structure, as shown below.
Merchant Events
The tables below provide a list of merchant events, including their names, descriptions, and hyperlinks to the data structure (schema) of each event's payload. Event names that support conditions are linked to the section detailing their supported conditions.
Order Events
| Event Name | Description | Payload Schema |
|---|---|---|
order.create (Supports conditions) |
Triggered when a new order is created. | Order schema |
order.status.update (Supports conditions) |
Triggered when an order's status is updated. | Order schema |
| order.payment_status.update | Triggered when an order's payment status changes to paid or unpaid. Note that unpaid includes pending, refunded, and voided statuses. |
Order schema |
Product Events
| Event Name | Description | Payload Schema |
|---|---|---|
| product.create | Triggered when a new product is created. | Product schema |
| product.update | Triggered when a product's details are updated. | Product schema |
| product.publish | Triggered when a product is published. | Product schema |
| product.delete | Triggered when a product is deleted. | Product deleted schema |
Abandoned Cart Events
| Event Name | Description | Payload Schema |
|---|---|---|
| abandoned_cart.created | Triggered when a shopping cart is abandoned. | Abandoned Cart schema |
| abandoned_cart.completed | Triggered when an abandoned cart is completed. | Abandoned Cart schema |
Customer Events
| Event Name | Description | Payload Schema |
|---|---|---|
| customer.create | Triggered when a new customer account is created. | Customer schema |
| customer.update | Triggered when a customer's details are updated. | Customer schema |
| customer.merchant.update | Triggered when a merchant's details related to a customer are updated. | Payload |
| customer.login | Triggered when a customer logs in. | Customer schema |
Product Category Events
| Event Name | Description | Payload Schema |
|---|---|---|
| category.create | Triggered when a new category is created. | Category schema |
| category.update | Triggered when a category's details are updated. | Category schema |
| category.delete | Triggered when a category is deleted. | Category schema |
Event Conditions
The conditions field in the request body allows you to specify additional criteria for your webhook subscription. By setting conditions, you can filter the events that trigger the webhook. For instance, you may want to receive notifications only when an order's status changes to 'delivered' or if the payment method is 'Cash On Delivery'.
Note: Conditions are currently supported only for the order.create and order.status.update events.
Supported Conditions
| Condition Key | Data Type | Description | Possible Values |
|---|---|---|---|
delivery_option_id |
Integer | The delivery option ID in Zid. | Any valid delivery option ID |
status |
String | Filters the event based on the status of the order. | new, preparing, ready, inDelivery, delivered, cancelled |
payment_method |
String | Filters the event based on the payment method used. | Cash On Delivery, Credit Card, Bank Transfer |
Example Usage
To set conditions, include the conditions field in the request body when creating or updating a webhook subscription. Here's an example:
{
"conditions": {
"delivery_option_id": "55",
"payment_method": "Cash On Delivery"
}
}