Legacy This page is reference for integrations already built on the Order Submit API. It remains supported. New integrations use the WHCC API.

Webhook Types

There are two types of webhook to expect, Status and Event. This page documents the V2 (JSON) payload format. If your integration receives application/x-www-form-urlencoded bodies instead of JSON, you're on the legacy V1 format — see V1 Webhook Format.

Identifying fields

Four fields appear on every notification below and together identify what the notification is about:

Branch on EventType, not on Event

Event alone does not name the event. An accepted order and a rejected one both arrive as "Event": "Processed", and only Status separates them — so any code that switches on Event by itself treats a rejection as an acceptance. EventType is the single field that tells them apart, and it is the same vocabulary you use to select events when subscribing.

Status

The status webhook lets you know if your order has been completely accepted or rejected. It is possible for an order to be rejected if there is an issue accessing the image assets included in the order request JSON.

Accepted Example

1
2
3
4
5
6
7
8
9
10
11
{
	"Status": "Accepted",
	"Errors": [],
	"OrderNumber": 99000341,
	"Event": "Processed",
	"ConfirmationId": "f245d035-0c0d-446c-81f4-dbe1e2802801",
	"EntryId": "1687452093",
	"Reference": "1298447712",
	"SequenceNumber": "0",
	"EventType": "order.accepted"
}

Rejected Example

A rejected order has no OrderNumber, since one was never assigned.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
	"Status": "Rejected",
	"Errors": [{
		"ErrorCode": "400.01",
		"Error": "Image hash value doesn't match, order canceled.",
		"AssetPath": "https://images.example-partner.com/27aa22c4-4cf4-44c8-b80a-ad1f80540443.jpg"
	}],
	"Event": "Processed",
	"ConfirmationId": "da99f6f0-2ba7-4bee-a348-8f5ba59fed77",
	"EntryId": "c2496f39-849d-4017-a9bf-a43c646b7f88",
	"Reference": "EP-Q-c2496f39",
	"SequenceNumber": "1",
	"EventType": "order.rejected"
}

See Errors for the full list of ErrorCode values.

Event

The event webhook lets you know about a change in production status of your order. The Event field tells you which one you received: Shipped or Order Cancelled. Look for a specific event value when processing this webhook type — more may be added in the future.

Shipped

Sent when an order (or part of an order) ships. ShippingInfo is an array of tracking entries. A multi-package order can arrive either way: as a single Shipped webhook whose ShippingInfo array holds several entries, or as several separate Shipped webhooks, one per package. Expect one or more Shipped webhooks per order, and process every entry in ShippingInfo — each webhook carries the complete tracking list known at the moment it was sent. That list grows: a second Shipped webhook with the same key, sent moments later, routinely carries additional tracking numbers as more packages are scanned. Merge ShippingInfo on repeat rather than discarding it, as described in Delivery, Retries & Idempotency.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
	"ShippingInfo": [{
		"Carrier": "FedEx",
		"ShipDate": "2026-05-08T16:59:59-05:00",
		"TrackingNumber": "9261200011223344556677",
		"TrackingUrl": "https://www.fedex.com/fedextrack/?trknbr=9261200011223344556677",
		"Weight": 1.0
	}],
	"OrderNumber": 99000918,
	"Event": "Shipped",
	"ConfirmationId": "a501c238-e91d-4766-853e-598dc6851338",
	"EntryId": "prspctr-Zq8mWkTn3XcRpLFB6-301488-1",
	"Reference": "ETSY_COM:5183660044-198372640551",
	"SequenceNumber": "1",
	"EventType": "order.shipped"
}

Order Cancelled

Sent when an order is canceled. V2 integrations only — V1 integrations never receive this event.

1
2
3
4
5
6
7
8
9
{
	"Event": "Order Cancelled",
	"OrderNumber": 99000201,
	"ConfirmationId": "f7889680-3aed-4dad-8942-090f6b3ce979",
	"EntryId": "prspctr-Xk2mQTn7YRbLpEFA9-452193-1",
	"Reference": "#1005-8091234567890",
	"SequenceNumber": "1",
	"EventType": "order.cancelled"
}