Webhooks

Overview

Webhooks allow OrbisCommerce to push event notifications to your server the moment something happens — no polling required.

Register a Webhook

POST /v1/webhooks

{
  "url": "https://yourapp.com/webhooks/orbiscommerce",
  "events": [
    "shipment.created",
    "label.generated",
    "tracking.updated",
    "tracking.delivered"
  ],
  "secret": "your_signing_secret"
}

Available Events

Payload Format

All webhook payloads share the same envelope:

{
  "id": "evt_01HXYZ9999MNOP",
  "event": "tracking.delivered",
  "created_at": "2025-06-03T18:42:00Z",
  "data": {
    "tracking_number": "9400111899223456789012",
    "carrier": "usps",
    "status": "delivered",
    "delivered_at": "2025-06-03T18:40:00Z"
  }
}

Verifying Signatures

Every webhook request includes an Orbis-Signature header. Always verify this to confirm the request came from OrbisCommerce.

import { createHmac } from "crypto";

function verifyWebhook(
    payload: string,
    signature: string,
    secret: string,
): boolean {
    const expected = createHmac("sha256", secret)
        .update(payload)
        .digest("hex");
    return `sha256=${expected}` === signature;
}

// In your handler:
const payload = await request.text();
const signature = request.headers.get("Orbis-Signature") ?? "";

if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET!)) {
    return new Response("Unauthorized", { status: 401 });
}

Retries

If your endpoint returns a non-2xx status, OrbisCommerce retries with exponential backoff:

After 5 failed attempts the webhook is marked as failed and you will receive an email alert.