Custom channels

A custom channel lets your own webshop, ERP or any other order source you control send orders into Zippendo, when there is no ready-made connection for it. It works in two directions:

Push orders in: your system sends signed webhook events to the channel’s own ingest URL, or calls the REST API (official SDKs available).
Hear back: subscribe to Zippendo’s outbound webhooks (shipment.dispatched, tracking.updated and more) to receive tracking numbers and status changes.

1. Create the channel

In app.zippendo.com, click Order channels, open the Catalog tab and click Create channel on the Custom channel card. Or create it through the API:

curl -X POST https://api.zippendo.com/orgs/{orgId}/order-channels \
  -H "Authorization: Bearer zipp_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "My webshop", "type": "custom" }'

2. Generate the signing secret

On the channel’s settings page, click Generate secret, or call POST /orgs/{orgId}/order-channels/{channelId}/webhook-secret. The response contains the ingest URL and the secret:

{
  "secret": "zwhs_...",
  "webhookUrl": "https://api.zippendo.com/webhooks/order-channels/{channelId}",
  "createdAt": "2026-09-02T12:00:00.000Z"
}

The secret is shown only once. Store it in your system’s configuration. Replacing the secret creates a new one and stops the old one working immediately. Revoking it makes the ingest URL reject every push until a new secret exists.

3. Push orders

Send a POST to the ingest URL with two headers:

Header	Value
`X-Zippendo-Topic`	`order.created`, `order.updated`, `order.cancelled`, or `ping`
`X-Zippendo-Signature`	HMAC-SHA256 of the raw request body, hex-encoded, keyed with your signing secret

import crypto from "node:crypto"

const body = JSON.stringify(order)
const signature = crypto.createHmac("sha256", process.env.ZIPPENDO_WEBHOOK_SECRET)
  .update(body)
  .digest("hex")

await fetch(webhookUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Zippendo-Topic": "order.created",
    "X-Zippendo-Signature": signature
  },
  body
})

Order payload (`order.created` / `order.updated`)

Both topics behave identically: the order is upserted on externalId, so redeliveries and out-of-order updates are safe. Push whichever your system finds easier.

{
  "externalId": "SO-10422",
  "orderNumber": "#1042",
  "customerName": "Anna Jensen",
  "customerEmail": "[email protected]",
  "shippingAddress": {
    "name": "Anna Jensen",
    "address1": "Nørregade 12",
    "city": "København",
    "postalCode": "1165",
    "countryCode": "DK",
    "phone": "+45 12 34 56 78"
  },
  "orderLines": [
    { "name": "Wool Sweater", "sku": "SKU-1042-BLK", "quantity": 2, "unitPrice": 499.0, "weight": 0.5, "weightUnit": "kg" }
  ],
  "totalAmount": 998.0,
  "currency": "DKK",
  "shippingMethodTitle": "GLS Hjemmelevering"
}

Field	Required	Notes
`externalId`	✔	Your system’s order id, used as the idempotency key
`orderNumber`	✔	Human-readable order number
`orderLines`	✔	At least one line (`name`, `quantity`; optionally `sku`, `unitPrice`, `weight`, …)
`shippingAddress`		Needed for a shipment to be created
`shippingMethodTitle`		Matched against the channel’s shipping-method mappings to choose a shipping rule
`serviceCode`		Explicit `{carrier}:{product}:{ruleId}[\|{servicePointId}]` code; wins over the mapping
`customerName`, `customerEmail`, `subtotalAmount`, `totalAmount`, `currency`, `notes`		Optional metadata

Cancel payload (`order.cancelled`)

{ "externalId": "SO-10422" }

Connectivity test (`ping`)

Any signed body with X-Zippendo-Topic: ping returns 200 { "received": true } without changing any data. Use it to check your signature code.

Responses

Status	Meaning
`200`	Delivery accepted and processed
`400`	Missing or unknown topic header, a payload that failed validation, or a channel that is turned off (Channel enabled is off)
`401`	Signature verification failed (wrong secret, missing header, or no secret minted yet)
`404`	Unknown channel id
`429`	Ingest rate limit reached. Retry after the `Retry-After` delay
`5xx`	Processing failed. Retry the delivery: the upsert makes redelivery safe

What happens to a pushed order

The order is upserted into the channel (inheriting the channel’s brand, if any).
A shipping rule is resolved: the explicit serviceCode, else the channel’s shipping-method mappings matched against shippingMethodTitle.
A shipment is created. Shipments with a matched rule are ready to send. With only a Default sender address set, a draft is created instead.
If Send shipments automatically is on for the channel, a shipment with a matched rule is sent to the carrier immediately, and the label lands in Zippendo (automatic printing on the rule applies).

REST alternative

If you prefer request/response over webhooks, create orders through the API with an API token:

curl -X POST https://api.zippendo.com/orgs/{orgId}/orders \
  -H "Authorization: Bearer zipp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderChannelId": "{channelId}",
    "orderNumber": "#1042",
    "externalId": "SO-10422",
    "orderLines": [{ "name": "Wool Sweater", "quantity": 2 }],
    "shippingAddress": { "name": "Anna Jensen", "address1": "Nørregade 12", "city": "København", "postalCode": "1165", "countryCode": "DK" },
    "shippingMethodTitle": "GLS Hjemmelevering"
  }'

A duplicate externalId on the same channel returns 409 ORDER_EXISTS. Treat it as “already received”.
Passing shippingRuleId or shippingMethodTitle (or turning on Send shipments automatically for the channel) creates the shipment in the same call, exactly like a push.
Order channels are part of the public API, so the SDKs cover every step: create the channel, generate the secret, push orders and list shipments.

Getting tracking back

Zippendo notifies your system through outbound webhooks: subscribe to shipment.dispatched and tracking.updated in Settings → Webhooks. Shipments carry your order number as their reference, and the payload includes the orderId for lookups.

Start

Quickstarts

Fulfillment flow

Connections

Operations

Organization & account

1. Create the channel

2. Generate the signing secret

3. Push orders

Order payload (`order.created` / `order.updated`)

Cancel payload (`order.cancelled`)

Connectivity test (`ping`)

Responses

What happens to a pushed order

REST alternative

Getting tracking back

Next steps

Outbound webhooks

API reference

​1. Create the channel

​2. Generate the signing secret

​3. Push orders

​Order payload (order.created / order.updated)

​Cancel payload (order.cancelled)

​Connectivity test (ping)

​Responses

​What happens to a pushed order

​REST alternative

​Getting tracking back

​Next steps

Outbound webhooks

API reference

1. Create the channel

2. Generate the signing secret

3. Push orders

Order payload (`order.created` / `order.updated`)

Cancel payload (`order.cancelled`)

Connectivity test (`ping`)

Responses

What happens to a pushed order

REST alternative

Getting tracking back

Next steps