Custom channel API

A custom channel is for a webshop, ERP, or WMS Zippendo does not have a one-click integration for. This page is every control on create and settings, plus how to send an order. The catalog walkthrough is Connect order channels. Payload reference: Custom channels. Open Order Channels → Available integrations (?tab=available-integrations). The Custom channel card reads Connect your own webshop or ERP system. Features: Signed webhook order ingestion, Full REST API with official SDKs, Automatic shipment creation and dispatch. The button is Create channel.

Order Channels Available integrations tab with the Custom channel card and Create channel button — Custom channel card on Available integrations

Create the channel

Click Create channel. Modal id create-custom-channel. Title Create custom channel. Subtitle: A channel for your own webshop or ERP integration.

Create custom channel modal with Channel name filled as My webshop, Create channel, and Cancel — Create custom channel modal with Channel name

Control	Required	Copy in the UI
Channel name	Yes	Placeholder `e.g. My webshop`. Create channel stays disabled until the name is non-empty.
Brand	No	The whole field (label Brand plus picker) is shown only if the organization has brands. Helper: Orders from this channel belong to this brand. Hidden in orgs with no brands.
Hint	—	After creating the channel you will get an ingest URL and a signing secret, so your system can push orders to Zippendo.
Create channel	—	Becomes Creating…. Toast Order channel created successfully / Failed to create order channel.
Cancel	—	Closes the modal.

On success Zippendo opens the new channel’s settings.

Order ingestion

Header title is the channel name. Description: Your own integration: push orders to the ingest URL, or use the API and SDKs. View documentation opens the custom channels reference. Loading: Loading channel…

Card title Order ingestion. Description: Your system pushes signed order events to the ingest URL below. Every request must carry an HMAC-SHA256 signature of the raw body, computed with the signing secret.

Control	Copy in the UI
Ingest URL	Read-only. Production looks like `https://api.zippendo.com/webhooks/order-channels/{channelId}`. Copy → Copied to clipboard. / Could not copy to clipboard.
Generate secret	First time. Becomes Generating…. Toast Signing secret generated. / Could not generate the signing secret.
Rotate secret	After a secret exists. Confirm: Rotate the signing secret? Your integration will be rejected until it signs with the new secret.
Revoke	Confirm: Revoke the signing secret? All order pushes will be rejected until a new secret is generated. Toast Signing secret revoked. / Could not revoke the signing secret.
Active line	Active signing secret created {date}

The Ingest URL in screenshots may show http://localhost:8000/… because these docs were captured against a local environment. Copy the URL from your channel settings.

After Generate secret or Rotate secret, the plaintext is shown once:

Order ingestion with one-time signing secret, Copy, Revoke, and Rotate secret — Copy the signing secret immediately — it is only shown once

Warning: Copy the secret now — it is only shown once. Rotating it later invalidates the current one immediately. The secret starts with zwhs_. There is no “enable webhooks” toggle — minting a signing secret is what turns ingest on.

Send an order

POST 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 the signing secret

order.created and order.updated both upsert on externalId. order.cancelled body is { "externalId": "…" }. ping returns 200 { "received": true } without touching data.

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
})

Required payload fields: externalId, orderNumber, orderLines (at least one line with name and quantity). Optional: customerName, customerEmail, shippingAddress, subtotalAmount, totalAmount, currency, notes, shippingMethodTitle, serviceCode. Full field table: Custom channels.

Status	Meaning
`200`	Accepted and processed
`400`	Missing/unknown topic, or the payload failed validation
`401`	Signature failed (wrong secret, missing header, or no secret minted) — `WEBHOOK_SIGNATURE_INVALID`
`404`	Unknown channel id
`429`	Ingest rate limit — retry after `Retry-After`
`5xx`	Processing failed — retry; upsert makes redelivery safe

When Channel enabled is off, pushes are rejected until you turn it back on. REST alternative: POST /orgs/{orgId}/orders with orderChannelId and an API token. Duplicate externalId on the same channel returns 409 ORDER_EXISTS. Tracking back to your system uses org Webhooks (shipment.dispatched, tracking.updated), not a per-channel callback. There is no shipping-method mapping UI on this screen. A successful push lands under Orders. Status can be Error when Zippendo imported the order but could not create a ready shipment (no matching shipping rule or incomplete address). The order is still on the channel.

Orders list showing an ingested custom-channel order — Orders list after a signed ingest

Operations

Field	Saves	Copy in the UI
Channel enabled	Immediately	When disabled, all order pushes to this channel are rejected. This is the enable/disable control.
Auto-dispatch shipments	Save changes	Book the carrier automatically when an incoming order matches a shipping rule. Off by default.
Brand	Immediately	Label Brand. Helper: Orders from this channel belong to this brand. The picker itself only appears when the organization has brands.
Default sender address	Save changes	Used for shipments when no shipping rule matches the order. Placeholder Select address. Empty: No addresses yet.
Last order received	Display	When this channel last received an order. Timestamp, or Never.

Save changes / Saving… applies auto-dispatch and the default address. Toast Order channel updated successfully / Failed to update order channel.

Enable, disable, and disconnected

Turn Channel enabled off. The Connected stores card shows Disabled (not Disconnected). Custom channels stay on Connected stores — they are never leftover Disconnected channels rows.

Connected stores custom channel card with Disabled badge, Custom integration subtitle, and No orders received yet or Last order received — Disabled custom channel on Connected stores

An Active custom card shows Custom integration, Connected date, and Last order received {date} or No orders received yet. Leftover platform stores (no live integration) appear under Disconnected channels with No active integration and Remove. That is not a custom channel. See Order channel settings.

Delete

Danger zone → Delete channel. Description: Remove this custom channel. Your integration will no longer be able to push orders.

Confirm: Delete this custom channel? Its ingest URL stops accepting orders immediately. Button Delete / Deleting…. Toast Order channel deleted successfully / Failed to delete order channel.

Connect order channels

Create the channel from the catalog, then open Orders.

Custom channels reference

Full ingest payload, cancel, ping, and REST examples.

Order channel settings

Enable, disable, and leftover disconnected channels.

Create an API token

Token for POST /orgs/{orgId}/orders instead of signed ingest.

Overview

Shipments

Orders & channels

Carriers

Connect a carrier

Connect an integration

Printing

Automation

Account

Search & dashboard

API & events

Custom channel API

Create the channel

Order ingestion

Send an order

Operations

Enable, disable, and disconnected

Delete

Connect order channels

Custom channels reference

Order channel settings

Create an API token

​Create the channel

​Order ingestion

​Send an order

​Operations

​Enable, disable, and disconnected

​Delete

​Related

Connect order channels

Custom channels reference

Order channel settings

Create an API token

Create the channel

Order ingestion

Send an order

Operations

Enable, disable, and disconnected

Delete

Related