# Webhooks ## Introduction Webhooks allow your application to receive real-time notifications about events in your merchOne orders. When specific events occur (order cancellation, shipment, tracking updates, etc.), merchOne sends a `POST` request to your configured webhook URL with event details in JSON format. ## Configuration {% stepper %} {% step %} ### Log in and open dashboard Log in to your merchOne account and navigate to the dashboard. {% endstep %} {% step %} ### Open Stores settings Navigate to the **Stores** page and access the **Settings** for the specific store where you wish to add a webhook. {% endstep %} {% step %} ### Find the Webhook section Scroll to the **Webhook** section. {% endstep %} {% step %} ### Add your webhook URL Add your webhook URL to the **Webhook URL** field. {% endstep %} {% step %} ### Save Click **Save**. {% endstep %} {% endstepper %} {% hint style="warning" %} The webhook URL is stored with the order at creation time. If you change or remove the webhook URL after an order is created, the changes will **not** apply to existing orders. Make sure your webhook URL is correctly configured before placing orders. {% endhint %} ## Webhook Delivery ### Request Format * Method: `POST` * Content-Type: `application/json` * Timeout: 60 seconds ### Retry Policy If your webhook endpoint fails to respond with a `2xx` status code, merchOne will automatically retry the delivery: | Attempt | Wait Time | | --------- | ---------- | | 1st retry | 1 minute | | 2nd retry | 5 minutes | | 3rd retry | 10 minutes | | 4th retry | 20 minutes | | 5th retry | 30 minutes | If your endpoint accumulates 10 or more failed webhook deliveries in a single day, you will receive a notification email. ### Expected Response Your endpoint should return a `200 OK` (or any `2xx`) status code to acknowledge receipt. The response body is ignored. ``` HTTP/1.1 200 OK ``` ## Webhook Events merchOne supports the following webhook event types: | Event Type | Description | | ------------------------- | --------------------------------------------------- | | `shipment_sent` | Triggered when an order shipment is dispatched | | `shipment_tracking_event` | Triggered when a tracking status update is received | | `order_canceled` | Triggered when an order is canceled | | `order_failed` | Triggered when an order encounters an error | | `order_commented` | Triggered when a comment is added to an order | ### Event-Specific Data Fields Each webhook event includes the full `order` object plus event-specific data: | Event Type | Extra Fields | Description | | ------------------------- | ------------ | -------------------------------------------------- | | `shipment_sent` | `shipment` | Shipment details with tracking info and items | | `shipment_tracking_event` | `event` | Tracking status, location, details, and date | | `order_canceled` | `author` | Who canceled the order (API, System, or user name) | | `order_failed` | `reason` | Error message describing why the order failed | | `order_commented` | `comment` | The comment text added to the order | ## Event Payloads ### Shipment Sent (`shipment_sent`) Triggered when an order shipment is dispatched from the fulfillment center. {% code title="shipment\_sent.json" %} ```json { "type": "shipment_sent", "created": "2025-05-02T12:48:56.000000Z", "data": { "shipment": { "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "tracking_number": "00340434161094042557", "tracking_url": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=00340434161094042557", "shipped_at": "2025-05-02T12:48:56.000000Z", "items": [ { "item_id": 12345, "item_external_id": "your-sku-123", "quantity": 3 } ] }, "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "FULFILLED", "status_label": "Fulfilled", "created_at": "2025-05-02T12:45:35.000000Z", "updated_at": "2025-05-02T12:48:56.000000Z", "shipments": [ { "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "tracking_number": "00340434161094042557", "tracking_url": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=00340434161094042557", "shipped_at": "2025-05-02T12:48:56.000000Z", "items": [ { "item_id": 12345, "item_external_id": "your-sku-123", "quantity": 3 } ] } ], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} ### Shipment Tracking Event (`shipment_tracking_event`) Triggered when a tracking status update is received for a shipment. {% code title="shipment\_tracking\_event.json" %} ```json { "type": "shipment_tracking_event", "created": "2025-05-03T08:15:00.000000Z", "data": { "event": { "status": "in_transit", "location": "Berlin, Germany", "details": "Package is in transit to destination", "date": "2025-05-03T08:12:00.000000Z" }, "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "FULFILLED", "status_label": "Fulfilled", "created_at": "2025-05-02T12:45:35.000000Z", "updated_at": "2025-05-03T08:15:00.000000Z", "shipments": [ { "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "tracking_number": "00340434161094042557", "tracking_url": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=00340434161094042557", "shipped_at": "2025-05-02T12:48:56.000000Z", "items": [ { "item_id": 12345, "item_external_id": "your-sku-123", "quantity": 3 } ] } ], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} Possible tracking statuses: * `in_transit` - Package is on the way * `out_for_delivery` - Package is out for delivery * `delivered` - Package has been delivered * `exception` - Delivery exception occurred * `returned` - Package returned to sender ### Order Canceled (`order_canceled`) Triggered when an order is canceled. {% code title="order\_canceled.json" %} ```json { "type": "order_canceled", "created": "2025-11-27T10:26:09.000000Z", "data": { "author": "via API", "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "CANCELED", "status_label": "Canceled", "created_at": "2025-11-27T09:00:00.000000Z", "updated_at": "2025-11-27T10:26:09.000000Z", "shipments": [], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} Possible `author` values: * `"via API"` - Canceled via API request * `"by System (Automatic)"` - Automatically canceled by the system * `"by John Doe"` - Canceled by a user * `"by our administrator, John Doe"` - Canceled by an admin ### Order Failed (`order_failed`) Triggered when an order encounters an error during processing. {% code title="order\_failed.json" %} ```json { "type": "order_failed", "created": "2025-11-27T10:26:19.000000Z", "data": { "reason": "Invalid image file: minimum resolution requirement not met", "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "FAILED", "status_label": "Failed", "created_at": "2025-11-27T09:00:00.000000Z", "updated_at": "2025-11-27T10:26:19.000000Z", "shipments": [], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} ### Order Commented (`order_commented`) Triggered when a comment is added to an order by merchOne staff. {% code title="order\_commented.json" %} ```json { "type": "order_commented", "created": "2025-11-27T10:26:28.000000Z", "data": { "comment": "Your order is being prepared with special care.", "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "IN_PRODUCTION", "status_label": "In Production", "created_at": "2025-11-27T09:00:00.000000Z", "updated_at": "2025-11-27T10:26:28.000000Z", "shipments": [], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} ## Troubleshooting ### Not receiving webhooks? {% stepper %} {% step %} ### Verify webhook URL Verify your webhook URL is correctly configured in Store Settings. {% endstep %} {% step %} ### Check endpoint accessibility Ensure your endpoint is publicly accessible (not behind a firewall). {% endstep %} {% step %} ### Return correct status Check that your endpoint returns a `200 OK` response. {% endstep %} {% step %} ### Verify SSL Verify your SSL certificate is valid (HTTPS required). {% endstep %} {% endstepper %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.merchone.com/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.