Webhooks quickstart

Webhooks tell your own systems the moment something happens in Zippendo, for example when a shipment is sent or a tracking status changes, so your webshop or ERP stays up to date without asking the API over and over.

Webhooks are included in every plan.

1. Add a webhook

Open Webhooks

In app.zippendo.com, open the organization menu at the bottom of the sidebar, click Manage, then Webhooks.

Create the webhook

Click Add webhook. Enter a Name and your Endpoint URL, tick the Events you want, and click Create webhook.

Get the signing secret

Zippendo creates a signing secret for every webhook. The app does not show it: read it with the API from GET /orgs/{orgId}/webhooks/{webhookId}, or from the response when you create the webhook through the API with POST /orgs/{orgId}/webhooks. Store it on your server and verify the signature on every delivery.

2. Events

Event	Sent when
`shipment.created`	A shipment is created
`shipment.updated`	A shipment is changed
`shipment.dispatched`	A shipment is sent to the carrier
`shipment.cancelled`	A shipment is deleted
`shipment.error`	Sending a shipment to the carrier fails
`order.created`	An order is created in the app or through the API
`order.updated`	An order is changed in the app or through the API
`order.cancelled`	An order is deleted in the app or through the API
`tracking.updated`	A parcel gets a new tracking event

Orders imported from an order channel don’t send order.* events. Send test on a webhook sends a webhook.test event to that one endpoint.

3. The delivery contract

Every delivery is an HTTPS POST with a JSON body of the form { "event", "timestamp", "brandId", "data" } and three headers:

Header	Value
`X-Webhook-Signature`	HMAC-SHA256 of the raw request body, hex-encoded, keyed with the webhook’s signing secret
`X-Webhook-Event`	The event name, for example `shipment.dispatched`
`X-Webhook-Id`	Unique delivery ID. A retried delivery keeps the same ID.

A delivery times out after 10 seconds. Any response other than 2xx, or a timeout, counts as a failure, and Zippendo tries again with a growing pause in between: up to 5 attempts in total. Every attempt, failed or not, is listed in the webhook’s Delivery log under Webhooks.

4. Handle deliveries

Your endpoint should:

Answer with a 2xx status quickly, and do heavy work in the background
Use HTTPS
Verify the signature before it trusts the body
Handle retries safely: use X-Webhook-Id to skip a delivery you already processed

import crypto from "node:crypto"

export async function POST(request) {
  const body = await request.text()

  const expected = crypto.createHmac("sha256", process.env.ZIPPENDO_WEBHOOK_SECRET)
    .update(body)
    .digest("hex")
  const signature = request.headers.get("x-webhook-signature") ?? ""
  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!valid) return new Response("invalid signature", { status: 401 })

  queueMicrotask(() => processZippendoEvent(JSON.parse(body)))
  return new Response("ok", { status: 200 })
}

5. Test while you develop

Use a tunnel (for example ngrok) to give your development server a public HTTPS address, such as https://your-tunnel.ngrok.io/webhooks/zippendo. Point a test webhook at it and click Send test.

Start

Quickstarts

Fulfillment flow

Connections

Operations

Organization & account

Webhooks quickstart

1. Add a webhook

2. Events

3. The delivery contract

4. Handle deliveries

5. Test while you develop

Next steps

Webhooks guide

REST API

​1. Add a webhook

​2. Events

​3. The delivery contract

​4. Handle deliveries

​5. Test while you develop

​Next steps

Webhooks guide

REST API

1. Add a webhook

2. Events

3. The delivery contract

4. Handle deliveries

5. Test while you develop

Next steps