Webhooks

What are webhooks?

Webhooks let OrbisCommerce send real-time HTTP POST notifications to your server when events occur — such as a shipment being delivered or a label being voided.

Setting up a webhook

Go to Settings → Webhooks
Click Add Endpoint
Enter your endpoint URL (must be publicly accessible over HTTPS)
Select the events you want to receive
Click Save

OrbisCommerce will send a test event to verify your endpoint is reachable.

Available events

Event	Description
`shipment.created`	A new label was generated
`shipment.voided`	A label was voided
`tracking.updated`	A new tracking scan was recorded
`tracking.delivered`	Shipment marked as delivered
`tracking.exception`	Delivery exception or failed attempt
`order.synced`	A marketplace order was imported

Webhook payload

All events share a common envelope:

{
  "id": "evt_01HXYZ123",
  "event": "tracking.delivered",
  "created_at": "2026-05-21T14:32:00Z",
  "data": {
    "shipment_id": "shp_01HXYZ456",
    "tracking_number": "1234567890",
    "carrier": "dhl",
    "delivered_at": "2026-05-21T14:30:00Z"
  }
}

Verifying webhook signatures

Each webhook request includes an X-OrbisCommerce-Signature header — an HMAC-SHA256 signature of the raw request body using your webhook secret.

import { createHmac } from 'crypto'

function verifySignature(body: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex')
  return `sha256=${expected}` === signature
}

Find your webhook secret under Settings → Webhooks → your endpoint → Secret.

If your endpoint returns a non-2xx status, OrbisCommerce retries the event up to 5 times with exponential backoff (1 min, 5 min, 30 min, 2 hr, 8 hr). After 5 failed attempts, the event is marked as failed and logged in your webhook dashboard.

Testing webhooks locally

Use ngrok or Cloudflare Tunnel to expose your local server and receive webhook events during development.