Webhook Integration Guide

What are webhooks?

A webhook is an HTTP POST that Superroute sends to a URL you configure whenever something happens — an order is created, a delivery is completed, a tracking event is recorded. You build a receiver endpoint, we deliver the event there.

How delivery works

Events are queued and sent asynchronously. Each request carries an HMAC-SHA256 signature so you can verify it really came from us. Failed deliveries (non-2xx response or timeout) are retried with exponential backoff up to 5 times.

Security model

You configure a shared secret on the settings page. Every outgoing webhook is signed with that secret. Your receiver recomputes the signature and compares — if they match, the payload is genuine and untampered.

Event Catalog

Five outbound event types are available. Each has its own URL field on your settings page — you can subscribe to any subset.

order.created

Fires whenever a local-delivery order (Delivery / Pickup / P2P) is created via any path — web form, REST/GraphQL API, ecommerce platform sync, automatic rules, import rows, etc. Excludes label-service and other non-delivery order types. Skipped in batch flow when order_create_async_postback_url is also configured for the same recipient. Configure with order_create_webhook_url.

Payload Examples

order.status_change

Fires on every order status transition — picked up, in transit, delivered, exception, cancelled. Configure with order_status_change_webhook_url.

Payload Examples

tracking.event

Fires on each tracking lifecycle event recorded against a package (information submitted, start delivery, delivery success, not delivered, etc.). Configure with tracking_event_webhook_url. Delivered and picked-up events also carry the proof of delivery: proof_files plus proof_files_detail (file_id, type, url, full_url, signed download URL). Photos uploaded after the event arrive as pod.files_updated.

Payload Examples

{
    "id": 90001,
    "order_id": 1001,
    "order_ref": "REF-001",
    "location_id": 12,
    "location_name": "Toronto Depot",
    "tracking_event_type": "D",
    "tracking_event_status_id": 500,
    "tracking_event_key": "deliver_success",
    "otep_status": "delivered",
    "proof_files": [
        "storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
        "storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg"
    ],
    "proof_files_detail": [
        {
            "file_id": 234567,
            "type": 1,
            "url": "storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
            "full_url": "https://api.superroute.ca/storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
            "signed_url": "https://api.superroute.ca/files/pod/234567?expires=1784748600&signature=8f2c1d...",
            "signed_url_expires_at": 1784748600
        },
        {
            "file_id": 234568,
            "type": 2,
            "url": "storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg",
            "full_url": "https://api.superroute.ca/storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg",
            "signed_url": "https://api.superroute.ca/files/pod/234568?expires=1784748600&signature=41ba90...",
            "signed_url_expires_at": 1784748600
        }
    ],
    "description": {
        "en": "Your parcel has been delivered successfully. Thank you!",
        "fr": "Votre colis a été livré avec succès. Merci !",
        "chs": "您的包裹已成功送达，感谢您的使用！",
        "cht": "您的包裹已成功送達，感謝您的使用！",
        "es": "Tu paquete ha sido entregado con éxito. ¡Gracias!",
        "de": "Ihr Paket wurde erfolgreich zugestellt. Vielen Dank!",
        "nl": "Uw pakket is succesvol afgeleverd, bedankt voor uw gebruik!",
        "pt": "Seu pacote foi entregue com sucesso. Obrigado!",
        "it": "Il tuo pacco è stato consegnato con successo. Grazie!",
        "sr": "Vaš paket je uspešno dostavljen, hvala vam što koristite naše usluge!",
        "hu": "Csomagja sikeresen kiszállításra került, köszönjük hogy használta szolgáltatásunkat!",
        "pl": "Twoja paczka została dostarczona pomyślnie. Dziękujemy!",
        "sk": "Váš balík bol úspešne doručený. Ďakujeme!",
        "cs": "Váš balík byl úspěšně doručen. Děkujeme!"
    },
    "tracking_number": [
        "SR000000001"
    ],
    "external_tracking_number": [
        "1Z999AA10123456784"
    ]
}

order.create_async

Fires once after a batch order import finishes processing. Payload contains the per-row results array. Configure with order_create_async_postback_url.

Payload Examples

POD Files Updated

Fired when a delivery photo or signature is added, replaced or removed (action: added / updated / removed) — one delivery per file, no more polling for attachments. Opt-in via pod_files_webhook_url.

Payload Examples

Order Deleted

Fired when an order is permanently deleted, so your system can mirror the removal. Opt-in via order_deleted_webhook_url.

Payload Examples

Order Cancel Failed

Fired when a cancel attempt is rejected (for example the order is already out for delivery), so your ops pipeline can monitor failed cancels without polling API responses. Opt-in via order_cancel_failed_webhook_url.

Payload Examples

Partner Locker Events

A separate webhook channel for third-party delivery partners integrating with smart lockers. Events are delivered to the endpoint configured for your partner account, and each endpoint can subscribe to any subset of event types.

partner_locker.delivery.doors_opened

Doors Opened — Fires the moment compartment doors open for a delivery attempt — whether the courier used the locker screen with the access code or the remote-open API — including reassignment re-openings. The opening block lists every opened compartment with its grid_id, hardware compartment_number and pickup_locker_number (sequential display number counted top-to-bottom within a column, then left to right).

Payload Examples

partner_locker.delivery.delivered

Delivered to Locker — Fires when a drop-off is confirmed and the parcels are in the locker. The payload includes the recipient pickup code.

Payload Examples

partner_locker.pickup.completed

Picked Up — Fires when the recipient has collected the deposited packages.

Payload Examples

partner_locker.delivery.failed

Delivery Failed — Fires when a delivery fails; per-package failure codes are included.

Payload Examples

partner_locker.delivery.expired

Expired — Fires when an unused delivery code or an uncollected deposit passes its expiry time.

Payload Examples

partner_locker.delivery.cancelled

Cancelled — Fires when a delivery is cancelled before completion.

Payload Examples

partner_locker.delivery.correction_reopened

Correction Reopened — Fires when the deposited compartments are reopened within the correction window to fix a wrong placement — from the locker screen or via the API. The correction block lists the reopened compartments.

Payload Examples

Signature & Verification: Partner locker webhooks use their own signing scheme: X-Webhook-Signature is base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), where the timestamp and delivery id come from the X-Webhook-Timestamp and X-Webhook-Delivery-Id headers. Also verify X-Webhook-Content-Digest (SHA-256 of the body) and reject stale timestamps. X-Webhook-Id stays stable across retries — use it for idempotency.

How to Configure: Endpoints are managed under Third-Party Delivery → Partner Locker → Settings, one endpoint per partner, with a selectable event list. Failed deliveries are retried with exponential backoff for up to 7 attempts before dead-lettering; dead-lettered events can be retried manually from the Events page.

How to Configure

You can configure webhooks at two levels: at the business level (covers everything) or per customer (overrides for that specific B2B sub-account).

1. Get to the settings

Log in and go to Settings → API & Webhooks. Customer-level overrides are on the customer detail page.

2. Set the signing secret

Pick any string at least 16 characters long, ideally 32+ random bytes. This secret is what your receiver will use to verify signatures.

3. Set the event URLs you want

Fill in only the URLs for events you care about. Leave the rest blank to skip them.

webhook_sign_secretYou configure a shared secret on the settings page. Every outgoing webhook is signed with that secret. Your receiver recomputes the signature and compares — if they match, the payload is genuine and untampered.

order_create_webhook_urlFires whenever a local-delivery order (Delivery / Pickup / P2P) is created via any path — web form, REST/GraphQL API, ecommerce platform sync, automatic rules, import rows, etc. Excludes label-service and other non-delivery order types. Skipped in batch flow when order_create_async_postback_url is also configured for the same recipient. Configure with order_create_webhook_url.

order_status_change_webhook_urlFires on every order status transition — picked up, in transit, delivered, exception, cancelled. Configure with order_status_change_webhook_url.

tracking_event_webhook_urlFires on each tracking lifecycle event recorded against a package (information submitted, start delivery, delivery success, not delivered, etc.). Configure with tracking_event_webhook_url. Delivered and picked-up events also carry the proof of delivery: proof_files plus proof_files_detail (file_id, type, url, full_url, signed download URL). Photos uploaded after the event arrive as pod.files_updated.

order_create_async_postback_urlFires once after a batch order import finishes processing. Payload contains the per-row results array. Configure with order_create_async_postback_url.

pod_files_webhook_urlFired when a delivery photo or signature is added, replaced or removed (action: added / updated / removed) — one delivery per file, no more polling for attachments. Opt-in via pod_files_webhook_url.

order_deleted_webhook_urlFired when an order is permanently deleted, so your system can mirror the removal. Opt-in via order_deleted_webhook_url.

order_cancel_failed_webhook_urlFired when a cancel attempt is rejected (for example the order is already out for delivery), so your ops pipeline can monitor failed cancels without polling API responses. Opt-in via order_cancel_failed_webhook_url.

Signature & Verification

Every outgoing webhook carries a hex-encoded HMAC-SHA256 signature in the request header. Your receiver must recompute the signature over the raw request body using the shared secret, and reject the request if it does not match.

Algorithm

HMAC-SHA256 (hex)

Header name

Signature

Verification steps

Read the raw request body before any parsing or middleware modifies it.
Compute hash_hmac('sha256', rawBody, sharedSecret) and hex-encode the result.
Compare with the Signature header using a constant-time comparison (hash_equals in PHP, crypto.timingSafeEqual in Node).
Return 2xx only if signatures match. Return 401 otherwise.

<?php
$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $rawBody, $sharedSecret);
if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Bad signature');
}
$payload = json_decode($rawBody, true);
// ... handle event ...
http_response_code(200);
echo 'ok';

const crypto = require('crypto');
const express = require('express');
const app = express();

app.use('/webhooks/superroute', express.raw({ type: 'application/json' }), (req, res) => {
    const received = req.header('Signature') || '';
    const expected = crypto.createHmac('sha256', sharedSecret)
        .update(req.body).digest('hex');
    if (!crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
        return res.status(401).send('Bad signature');
    }
    const payload = JSON.parse(req.body.toString());
    // ... handle event ...
    res.status(200).send('ok');
});

import hmac, hashlib
from flask import Flask, request, abort
app = Flask(__name__)

@app.route('/webhooks/superroute', methods=['POST'])
def webhook():
    received = request.headers.get('Signature', '')
    expected = hmac.new(shared_secret.encode(), request.data, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(received, expected):
        abort(401)
    payload = request.get_json()
    # ... handle event ...
    return 'ok', 200

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    received := r.Header.Get("Signature")
    mac := hmac.New(sha256.New, []byte(sharedSecret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    if !hmac.Equal([]byte(received), []byte(expected)) {
        w.WriteHeader(401); return
    }
    // ... handle event ...
    w.WriteHeader(200)
    w.Write([]byte("ok"))
}

require 'openssl'
require 'rack/utils'

post '/webhooks/superroute' do
  raw = request.body.read
  received = request.env['HTTP_SIGNATURE'] || ''
  expected = OpenSSL::HMAC.hexdigest('sha256', shared_secret, raw)
  halt 401 unless Rack::Utils.secure_compare(received, expected)
  payload = JSON.parse(raw)
  # ... handle event ...
  status 200
  'ok'
end

Retry & Reliability

Your endpoint should respond with a 2xx status quickly. If it returns anything else, times out, or is unreachable, the delivery is retried.

Max attempts

5 (initial + 4 retries)

Per-attempt timeout

3 seconds

Backoff

Exponential — roughly 10s, 100s, 1000s, 10000s between attempts

Signature Verifier

Paste a payload you received from us along with the Signature header value and your secret — this tool recomputes the signature in your browser (nothing leaves this page) and tells you if it matches.

Raw request body (JSON)

Your signing secret

Signature header value (the hex string we sent)

Computed signature

Send a Test Webhook

Fire a real, properly-signed webhook from our server to a URL you provide. Use this to test that your receiver is reachable, that you parse the payload correctly, and that your signature verification logic works.

Receiver URL

Signing secret

Event type

Payload (optional — leave blank for a default sample)

HTTP Status / Response Time

Signature sent

Response Body

Recent Webhook Deliveries

View the most recent webhook delivery attempts on your account — both real production events and tests sent from this page. Paste your Bearer token to load.

Bearer Token

Event type

Status

Time	Event	URL	Status	HTTP	Attempt	Time (ms)	Test?	Actions
No webhook deliveries found yet.

Best Practices

Acknowledge fast (HTTP 200) and process work asynchronously to stay under the 3-second timeout.
Always verify the signature before trusting the payload.
Treat events as at-least-once — dedupe on the order/tracking number.
Use HTTPS endpoints with a valid certificate.
Log incoming requests so you can replay them if your handler has a bug.