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

1

Log in and open dashboard

Log in to your merchOne account and navigate to the dashboard.

2

Open Stores settings

Navigate to the Stores page and access the Settings for the specific store where you wish to add a webhook.

3

Find the Webhook section

Scroll to the Webhook section.

4

Add your webhook URL

Add your webhook URL to the Webhook URL field.

5

Save

Click Save.

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.

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.

shipment_sent.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": []
    }
  }
}

Shipment Tracking Event (shipment_tracking_event)

Triggered when a tracking status update is received for a shipment.

shipment_tracking_event.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": []
    }
  }
}

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.

order_canceled.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": []
    }
  }
}

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.

order_failed.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": []
    }
  }
}

Order Commented (order_commented)

Triggered when a comment is added to an order by merchOne staff.

order_commented.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": []
    }
  }
}

Troubleshooting

Not receiving webhooks?

1

Verify webhook URL

Verify your webhook URL is correctly configured in Store Settings.

2

Check endpoint accessibility

Ensure your endpoint is publicly accessible (not behind a firewall).

3

Return correct status

Check that your endpoint returns a 200 OK response.

4

Verify SSL

Verify your SSL certificate is valid (HTTPS required).