# Webhooks ## Webhooks API Documentation ### Introduction Welcome to the Ayor Webhook API documentation. This guide helps third-party developers integrate with our webhook system to receive real-time event notifications securely and reliably. *** ### Webhook Overview Webhooks allow your system to receive automated event notifications (such as `order.created`) from Ayor. They are delivered as HTTPS POST requests to your specified endpoint. Events are pushed using Google Pub/Sub. *** ### Event Types You can subscribe to the following event types: * `order.created` * `order.updated` * `order.confirmed` * `order.shipped` * `order.delivered` * `order.cancelled` * `product.out_of_stock` * `subscription.renewed` * `subscription.expired` * `integration.failed` * `domain.connected` *** ### Integration Guide #### Payload Format Each webhook event is delivered as a Pub/Sub message structured like this: ```json { "deliveryAttempt": 1, "message": { "attributes": { "event_id": "", "event_type": "order.created", "shop_id": "", "timestamp": "2025-08-06T15:35:30.491494", "user_id": "" }, "data": "" }, "subscription": "projects/.../subscriptions/webhook---" } ``` #### Decoded Payload Example The `data` field contains a base64-encoded JSON object. After decoding, here is a sample payload for `order.created`: ```json { "event_id": "77d13351-0578-4f6f-ba5e-fb38405b75ba", "event_type": "order.created", "user_id": "2734", "timestamp": "2025-08-18T10:19:43.760875Z", "data": { "event_id": "77d13351-0578-4f6f-ba5e-fb38405b75ba", "order_id": "10e0e5ff-c844-4ad8-80f5-7024c5df8d39", "display_id": 33, "confirmation_status": "Pending", "delivery_status": null, "total_price": 1800, "delivery_price": 0, "currency": "DZD", "payment_method": "cod", "payment_status": "pending", "is_stop_desk": false, "shipping_id": null, "client_note": null, "created_at": "2025-08-18T10:19:39.680686+00:00", "updated_at": "2025-08-18T10:19:39.817185+00:00", "client_info": { "full_name": "Touares tou", "phone_number": "0770707070", "email": null, "state": "12 - Tébessa - تبسة", "city": "بئر العاتر" }, "custom_fields": [ { "field_id": 6, "field_name": "Custom", "custom_title": "Custom Address", "value": "sdfghjk", "item_id": null } ], "timestamp": "2025-08-18T10:19:43.757867", "order_lines": [ { "product_id": "b26bca7a-35cd-4397-bb5d-c5708a22c58c", "product_name": "Aqua di Gio", "variant_name": null, "quantity": 1, "unit_price": 1800, "reduced_price": null, "total_price": 1800, "sku": null, "shipping_id": null } ], "bundle_lines": [], "shop_info": { "shop_id": "52f9c4ea-7cbe-4b32-9696-99e9f32c5daf", "shop_name": "store", "shop_subdomain": "store" }, "landing_page_info": { "landing_page_id": "f29039b5-b670-438a-acd0-c5e88aea5b9a", "landing_page_title": "Aqua di Gio" } } } ``` #### Payload Schema (Field Reference) Each event includes a JSON payload with the following fields: | Field | Type | Required | Description | Allowed Values | | --------------------- | ------------------- | :-------------------------------------------: | -------------------------------------------------- | ------------------------------------------------------------------------ | | `event_id` | `string` | | Unique identifier of the event | | | `event_type` | `string` | | Type of event (e.g., `order.created`) | | | `user_id` | `string` | | ID of the user (merchant) | | | `timestamp` | `string (ISO 8601)` | | Time the event was generated | | | `order_id` | `string` | | Unique ID of the order | | | `display_id` | `integer` | | Merchant-facing order reference number | | | `confirmation_status` | `string` | | Status of order confirmation | `Pending`, `Confirmed`, `Callback`, `Cancelled` | | `delivery_status` | `string or null` | | Status of delivery, if available | `CREATED`, `IN_TRANSIT`, `PENDING`, `DELIVERED`, `CANCELLED`, `RETURNED` | | `total_price` | `decimal` | | Total order amount including products and delivery | | | `delivery_price` | `decimal` | | Delivery fee | | | `currency` | `string` | | Currency code (e.g., DZD) | | | `payment_method` | `string` | | Payment method used | `cod`, `stripe` | | `payment_status` | `string` | | Status of the payment | `pending`, `completed`, `failed` | | `is_stop_desk` | `boolean` | | Whether the order is a stop-desk pickup | | | `shipping_id` | `string or null` | | Shipping provider ID or tracking ref | | | `client_note` | `string or null` | | Customer-provided message | | | `created_at` | `string (ISO 8601)` | | Timestamp of order creation | | | `updated_at` | `string (ISO 8601)` | | Timestamp of last update to the order | | **`client_info` object** | Field | Type | Required | Description | | -------------- | ---------------- | :-------------------------------------------: | --------------------- | | `full_name` | `string` | | Customer full name | | `phone_number` | `string` | | Customer phone number | | `email` | `string or null` | | Customer email | | `state` | `string` | | Customer state/region | | `city` | `string` | | Customer city | **`custom_fields` array** Each field added by the merchant to their landing page: | Field | Type | Required | Description | | -------------- | ---------------- | :-------------------------------------------: | ------------------------------------ | | `field_id` | `integer` | | ID of the custom form field | | `field_name` | `string` | | Name of the custom field | | `custom_title` | `string` | | Label used on the landing page | | `value` | `string` | | Submitted value | | `item_id` | `string or null` | | Internal reference to the form entry | **`order_lines` array** One entry per product ordered: | Field | Type | Required | Description | | --------------- | ----------------- | :-------------------------------------------: | ------------------------------------------------- | | `product_id` | `string` | | ID of the product ordered | | `product_name` | `string` | | Name of the product variant | | `variant_name` | `string` | | Variant description (e.g., size, color) | | `quantity` | `integer` | | Number of units ordered | | `unit_price` | `decimal` | | Price per unit | | `reduced_price` | `decimal or null` | | Discounted price if applicable | | `total_price` | `decimal` | | Final price (unit × quantity or discounted total) | | `sku` | `string` | | Product SKU | | `shipping_id` | `string or null` | | Product-specific shipping ID | **`bundle_lines` array** Empty array if no bundles were ordered. **`shop_info` object** | Field | Type | Required | Description | | ---------------- | -------- | :-------------------------------------------: | ----------------- | | `shop_id` | `string` | | Unique shop ID | | `shop_name` | `string` | | Store name | | `shop_subdomain` | `string` | | Store’s subdomain | **`landing_page_info` object** | Field | Type | Required | Description | | -------------------- | -------- | :-------------------------------------------: | ------------------------------- | | `landing_page_id` | `string` | | ID of the landing page | | `landing_page_title` | `string` | | Title shown on the landing page | *** ### **Retry Behavior** * If your endpoint responds with a non-`2xx` status or times out, we retry the request using **exponential backoff**: * 1st retry: \~5 seconds after failure * Subsequent retries: delay doubles each time, up to 5 minutes between attempts * Each message is retried up to **5 times**. * If all retries fail, the message is sent to a **Dead Letter Queue (DLQ)** and will not be redelivered automatically. *** ### Best Practices * **Respond quickly** (<30s) with HTTP 2xx * **Process asynchronously** — don't block on business logic * **Verify signature** for authenticity * **Use `event_id`** to ensure idempotency * **Expect retries** and duplicate deliveries *** ### Support For technical support, contact: - -
*** *Last updated: August 7, 2025*