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:

1. Choose the event(s) you would like to subscribe to from the list of Supported Webhook Events below.

2. (Optional) If the event supports conditions, check out the Event Conditions section to learn how to populate the conditions field.

3. 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 App 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	Payload Schema
app.market.subscription.active	Send notification on successful activation of subscription	Active Schema
app.market.subscription.warning	Send notification 3 days before the last subscription date (T is the duration of the plan in days)	Warning Schema
app.market.subscription.suspended	Send notification on completion of subscription	Suspended Schema
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	Expired Schema
app.market.subscription.renew	Send notification on successful renewal of the same plan subscription 5 days before the last date	Renew Schema
app.market.subscription.upgrade	Send notification on upgrade of subscription	Upgrade Schema
app.market.subscription.refunded	Send notification on refund of subscription	Refunded Schema
app.market.application.install	Send notification on the installation of application	Install Schema
app.market.application.uninstall	Send notification on uninstallation of the application	Uninstall Schema
app.market.application.rated	Triggered when a merchant submits a rating or review for the app.	Rated Schema
app.market.private.plan.request	Triggered when a merchant submits a request for a private plan.	Private Plan Request Schema
app.market.application.authorized	Triggered when a merchant authorizes an app prior to installation.	Authorized Schema

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