Create a Webhook

Webhooks allow you to receive real-time data updates about various events.
For certain events, you can specify conditions under which the webhook should trigger,
allowing for more targeted data retrieval.

Supported Webhook Events

For more details on available events and their conditions,
please refer to the Supported Webhook Events page.

🔑Scopes

webhooks.read_write - Webhooks Read & Write

Request

Header Params

Authorization

string

required

The Authorization token is a unique key given to the third-party application (Partner) by Zid. It is used to authenticate the API requests made by the Partner application. The token verifies the partner's identity and ensures they have permission to access Zid's API but does not provide any specific user or store information. It should be included in the header of API requests when the partner application needs to access Zid's API.

Example:

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxMTciLCJqdGkiOiJhMTg5ZTg3MmYxMzhkMWVhYjU5MjVkMDkyMGE5NmI0YjliNjg0Y2E2ZTdmM2M2MjljZWYxNmQ4NDJjMmJlYmVhMjI4YTdmMTA0ZWQ4NWE5NCIsImlhdCI6MTY3OTU3Njk5OS41NjY4NzcsIm5iZiI6MTY3OTU3Njk5OS41NjY4OCwiZXhwIjoxNzExMTk5Mzk5LjQ4NjE1Mywic3ViIjoiMTgyNDc1Iiwic2NvcGVzIjpbInRoaXJkLXBhcnRpZXMtYXBpcyJdfQ.i07ef09nVNXGZF-g-QXpNoS2vlFQK_zntAqAMS4Az2XD2EyMLhxLZZRL-QlR11zUPqMmXjMAl_4ooKa3M3zkfZQ6Ga6qStvamk8RnC_39VUx0lfN2A4k65ERZpqwrMy6-t3dE99zay3aicIdNvbgi0zeuMSE5Tn99u-2AtSRa8ffbfAcYPPXacHrhdmlYzdiZS_x_skovFEow1E-nDjdL1WHqO92XdZ7RfNLkiYFTjZlZmM_UruvioaR3q6TXJbqRK_ZrziivezL8ohIQ2SBosUp58I29rlKzvlw_R2j0rKKYZbdxYDaxAHOISmOFKAlO66k7dNevAHI3s4uGIjoGA6ZXHknccWPLLLiaAQ0r64HV8GowW5dg2rhZNurJGDTnLlBQ6F-ql42ptHzSAfzzi576CEoN3gMVpgXcbntUY3reETkFsTBPUjeSuMpANMioXAA0GRp3Ut-84fTnrWxqsCW1WVUIx33HvmfCGPXIdkaCCWoA6G6KXo04MtFbKXQmXkK9esQWI-rqdVnMD3zSR3g3yFHZSL1U-mZeNja03706Rav1ordsRNOtRwtLuoRRbk9KasbUpEwqq4Ao9lqZZwRIjdEw-pQtnUT8V53fhmuuRIefCLFO7eGEtGUnh9o6Uh_pgi6AB6uSlnN9GEMGgI1alqvMmTjxvC-HHt0V-Y

X-Manager-Token

string

required

This token is used to authenticate and access information related to the store. It is obtained through an OAuth mechanism and is required to perform operations on the store's data. The X-Manager-Token should be included in the header of API requests that require store-related information.

Example:

eyJpdiI6Imh3L2dGbmJmRnVCOUY4WW5WQ2s3RFE9PSIsInZhbHVlIjoiZklpRnJyVGV1OWcrZUJBNk44bVp5SjZzSS92V3czcTJjbnJ2dFYvenZ3SFBtWHNSMFU3ZEMzZ0ZJNnpucVE4Ui9rNFdicUduOGpKUlg1VXdGOFFIaVUzZjZyUUZybWx3R0tNY3orUmxoUUUxQ29wSkEyVDZTVnVYb2dlUXJSVzBYVkdESjBpS0xiN05Hbndzc2wzV2N0YitGM1NEdkk4ckZZOTZsTFdEL1ZQRlJJTE5FQmttZng2elpwL1RCeXFRdUd1U3JTc0FHV1kySS80RFJaWlIyZ3gwM2FsQVRFbkt3VWtFOUQyKzdGOD0iLCJtYWMiOiJmZDQ0YzM4ODE0OWQxOWRhYWU0NDhhYmIzYzQ1MDAxMDAzODZjZGM3ZGM4NGJhMGNkMDEyYWZlM2UzYjAxMTI4IiwidGFnIjoiIn0=

Accept-Language

enum<string>

optional

Preferred language for the response. Defaults to en if not specified.

Allowed values:

enar

Example:

Body Params application/json

event

string

required

The event that the webhook will subscribe to. It represents the type of event that will trigger the webhook.

Example:

order.status.update

target_url

string

required

The URL to which Zid will send a payload when the subscribed event triggers. This is the endpoint that will receive the webhook data.

Example:

http://zid.sa

original_id

integer

required

An optional user-defined identifier for reference purposes. The original ID allows the user (Partner) to associate their own identifier with the webhook subscription.

Example:

subscriber

string

required

The name or identifier of the subscriber. It indicates the source or owner of the webhook subscription.

Example:

My App

conditions

object | null

optional

Additional conditions that can be specified for the webhook subscription.
This field allows filtering the webhook events based on specific criteria.
For example, you may want to be notified only when an order's status is 'delivered'
or if the payment method is 'Cash On Delivery'.

Supported Events: order.create and order.status.update

Key	Type	Description
delivery_option_id	integer	The delivery option ID in Zid.
status	string	One of these statuses: [new, preparing, ready, inDelivery, delivered, cancelled].
payment_method	string	One of these methods: [Cash On Delivery, Credit Card, Bank Transfer].

status

enum<string>

optional

The order status. Optional.

Allowed values:

newpreparingreadyinDeliverydeliveredcancelled

Example:

new

delivery_option_id

integer

optional

The delivery option ID in Zid. Optional.

Example:

payment_method

enum<string>

optional

The payment method. Optional.

Allowed values:

Cash On DeliveryCredit CardBank Transfer

Example:

Cash On Delivery

Example

{
    "event": "order.status.update",
    "target_url": "http://zid.sa",
    "original_id": 1,
    "subscriber": "My App",
    "conditions": {
        "status": "new",
        "delivery_option_id": 55,
        "payment_method": "Cash On Delivery"
    }
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.zid.sa/v1/managers/webhooks' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxMTciLCJqdGkiOiJhMTg5ZTg3MmYxMzhkMWVhYjU5MjVkMDkyMGE5NmI0YjliNjg0Y2E2ZTdmM2M2MjljZWYxNmQ4NDJjMmJlYmVhMjI4YTdmMTA0ZWQ4NWE5NCIsImlhdCI6MTY3OTU3Njk5OS41NjY4NzcsIm5iZiI6MTY3OTU3Njk5OS41NjY4OCwiZXhwIjoxNzExMTk5Mzk5LjQ4NjE1Mywic3ViIjoiMTgyNDc1Iiwic2NvcGVzIjpbInRoaXJkLXBhcnRpZXMtYXBpcyJdfQ.i07ef09nVNXGZF-g-QXpNoS2vlFQK_zntAqAMS4Az2XD2EyMLhxLZZRL-QlR11zUPqMmXjMAl_4ooKa3M3zkfZQ6Ga6qStvamk8RnC_39VUx0lfN2A4k65ERZpqwrMy6-t3dE99zay3aicIdNvbgi0zeuMSE5Tn99u-2AtSRa8ffbfAcYPPXacHrhdmlYzdiZS_x_skovFEow1E-nDjdL1WHqO92XdZ7RfNLkiYFTjZlZmM_UruvioaR3q6TXJbqRK_ZrziivezL8ohIQ2SBosUp58I29rlKzvlw_R2j0rKKYZbdxYDaxAHOISmOFKAlO66k7dNevAHI3s4uGIjoGA6ZXHknccWPLLLiaAQ0r64HV8GowW5dg2rhZNurJGDTnLlBQ6F-ql42ptHzSAfzzi576CEoN3gMVpgXcbntUY3reETkFsTBPUjeSuMpANMioXAA0GRp3Ut-84fTnrWxqsCW1WVUIx33HvmfCGPXIdkaCCWoA6G6KXo04MtFbKXQmXkK9esQWI-rqdVnMD3zSR3g3yFHZSL1U-mZeNja03706Rav1ordsRNOtRwtLuoRRbk9KasbUpEwqq4Ao9lqZZwRIjdEw-pQtnUT8V53fhmuuRIefCLFO7eGEtGUnh9o6Uh_pgi6AB6uSlnN9GEMGgI1alqvMmTjxvC-HHt0V-Y' \
--header 'X-Manager-Token: eyJpdiI6Imh3L2dGbmJmRnVCOUY4WW5WQ2s3RFE9PSIsInZhbHVlIjoiZklpRnJyVGV1OWcrZUJBNk44bVp5SjZzSS92V3czcTJjbnJ2dFYvenZ3SFBtWHNSMFU3ZEMzZ0ZJNnpucVE4Ui9rNFdicUduOGpKUlg1VXdGOFFIaVUzZjZyUUZybWx3R0tNY3orUmxoUUUxQ29wSkEyVDZTVnVYb2dlUXJSVzBYVkdESjBpS0xiN05Hbndzc2wzV2N0YitGM1NEdkk4ckZZOTZsTFdEL1ZQRlJJTE5FQmttZng2elpwL1RCeXFRdUd1U3JTc0FHV1kySS80RFJaWlIyZ3gwM2FsQVRFbkt3VWtFOUQyKzdGOD0iLCJtYWMiOiJmZDQ0YzM4ODE0OWQxOWRhYWU0NDhhYmIzYzQ1MDAxMDAzODZjZGM3ZGM4NGJhMGNkMDEyYWZlM2UzYjAxMTI4IiwidGFnIjoiIn0=' \
--header 'Accept-Language;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event": "order.status.update",
    "target_url": "http://zid.sa",
    "original_id": 1,
    "subscriber": "My App",
    "conditions": {
        "status": "new",
        "delivery_option_id": 55,
        "payment_method": "Cash On Delivery"
    }
}'

Responses

🟢200Created WebHook Information

application/json

Body

status

object

optional

The status of the webhook creation request. Possible statuses codes are ready, pending, inactive, and error.

string

optional

The UUID assigned to the webhook subscription by Zid.

Example:

3f6c6af7-6b9c-4cdd-8f10-7b309cfa32d1

event

string

optional

The event that the webhook is subscribed to.

Example:

order.status.update

target_url

string

optional

The URL to which Zid will send a payload when the subscribed event triggers.

Example:

http://zidstoreapp.com/webhook-endpoint

store_id

string

optional

The UUID of the store associated with the webhook.

Example:

f47ac10b-58cc-4372-a567-0e02b2c3d479

conditions

object | null

optional

The conditions under which the webhook will be triggered. These conditions were specified during the webhook creation and allow the webhook to be triggered only when certain criteria are met.

Supported Events: order.create and order.status.update

Key	Type	Description
delivery_option_id	integer	The delivery option ID in Zid.
status	string	One of these statuses: [new, preparing, ready, inDelivery, delivered, cancelled].
payment_method	string	One of these methods: [Cash On Delivery, Credit Card, Bank Transfer].

status

array[string]

optional

Example:

["new","ready","inDelivery","delivered"]

payment_method

array[string]

optional

Example:

["Cash On Delivery","Credit Card"]

original_id

string | null

optional

An optional user-defined identifier for reference purposes.

Example:

OrderUpdate123

subscriber

string

optional

The name or identifier of the subscriber or the source of the webhook.

Example:

InventoryManagerApp

active

boolean

optional

Indicates whether the webhook is active or not.

Example:

true

message

object (ResponseMessage)

optional

A message indicating the result of the webhook creation.

type

string

optional

The type of the message.

Example:

object

code

string

optional

The code associated with the message.

Example:

200

name

string

optional

The name of the message.

Example:

Success

description

string

optional

A detailed description of the message.

Example:

Order details retrieved successfully.

Example

{
    "status": {},
    "id": "3f6c6af7-6b9c-4cdd-8f10-7b309cfa32d1",
    "event": "order.status.update",
    "target_url": "http://zidstoreapp.com/webhook-endpoint",
    "store_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "conditions": {
        "status": [
            "new",
            "ready",
            "inDelivery",
            "delivered"
        ],
        "payment_method": [
            "Cash On Delivery",
            "Credit Card"
        ]
    },
    "original_id": "OrderUpdate123",
    "subscriber": "InventoryManagerApp",
    "active": true,
    "message": {
        "type": "object",
        "code": "200",
        "name": "Success",
        "description": "Order details retrieved successfully."
    }
}

Supported Webhook Events#

Request

Request samples

Responses

Supported Webhook Events