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.

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.

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 the conditions field.

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.

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"
  }
}

Overview#

How to Subscribe#

Merchant Events#

Order Events#

Product Events#

Abandoned Cart Events#

Customer Events#

Product Category Events#

Event Conditions#

Supported Conditions#

Example Usage#