Purpose

A webhook is a POST that Qapla' makes to a URL of yours when something happens to a shipment: its status changes, the courier records a new event. Instead of polling the API to find out whether anything changed, you receive the fact as soon as we know it.

Webhooks v2 are the generation that goes with the v2 API:

• same schema as the API: the payload carries the shipment in the same shape as GET /v2/shipments, so an integration has one data model;
• signed: every request carries an HMAC-SHA256 of the body, verifiable with a secret only you and we know;
• configurable: you choose when to receive (status changes only, the first time in a status, every courier event) and for which statuses;
• reliable: success = any 2xx, retries with backoff for about 22 hours, failed deliveries kept and replayable.

Configuration

A webhook is configured from the Control Panel, in Channel settings → Updates → “Webhook v2”. The same page is where you send tests, rotate the secret, browse and replay deliveries, and reactivate a switched-off endpoint. The endpoint belongs to the channel: with several channels, configure it on each of them, even with the same URL. Each channel can have up to 5 endpoints (disabled ones count too), for example the ERP receiving only status changes and customer care receiving every event.

On creation the Control Panel shows the signing secret, shaped as whsec_ followed by 64 hex characters. It is shown only once: copy it into your receiver's configuration right away. If you lose it, generate a new one (Secret rotation).

Event types

More types (labels, returns) will join the same catalogue. The type comes both in the body (type) and in the X-Qapla-Event-Type header.

Triggers

The trigger decides when a shipment event becomes a delivery to your endpoint. A Qapla' status is a status + detail pair (for instance EXCEPTION with detail "held in stock"): the first two triggers work on that pair.

The trigger in use comes in the payload as data.trigger.

Status filter

statuses is a list of Qapla' status names. Empty = all statuses. It applies after the trigger and on the status only, never on the detail: ["EXCEPTION"] takes every exception, whatever its detail. If you need specific details only, filter them on your side with data.event.statusDetailId.

Allowed values: WAITING_TO_COMPUTE, PENDING, INFO_RECEIVED, IN_TRANSIT, OUT_FOR_DELIVERY, FAILED_ATTEMPT, EXCEPTION, DELAY, PICKUP_POINT, DEPARTED, PROCESSING, RETURNED, DELIVERED. An unknown name is a configuration error.

Optional sections

include adds payload sections that are absent by default. Today it accepts a single value:

There is still one schema: the consignee field is either there or not, its shape does not change. include is a list rather than a yes/no so that it can take more sections without breaking the contract.

Test event

From the Control Panel you can send a webhook.test event to the endpoint right away. It is signed with your real secret, with the same headers as a real delivery: it is how you check the signature before going live. The Control Panel shows the HTTP status you returned, the duration and any error.

• same envelope as shipment.updated, with a fixed sample shipment (not one of yours); consignee is there only if the endpoint has include: ["consignee"];
• the id looks like evt_test_… and changes on every test;
• one attempt only: not retried and not listed among deliveries. A failed test does not count towards alerts and switch-off; a successful one (2xx) brings the endpoint back to healthy, resetting the failure count.

Your receiver must answer 2xx to webhook.test as well, and must not treat it as a real update.

Structure

One event per request, no batches. Content-Type: application/json, UTF-8.

New fields may appear in the resource (and therefore in the webhook) without an apiVersion change: your receiver must ignore fields it does not know.

Ordering and duplicates

Arrival order is not guaranteed. Deliveries are independent and may travel in parallel: an old event being retried does not hold back newer ones. This is deliberate: serial delivery would keep a "delivered" waiting for hours behind a temporary error on an earlier event.

The same event may arrive more than once: a retry after a timeout in which you had already processed the request, a replay. Use id (or X-Qapla-Event-Id) as the idempotency key: if you have already processed it, answer 2xx and do nothing else. A failed delivery can be replayed for 30 days (Replay): keep the ids at least that long.

When several endpoints of the same channel subscribe to the same event, each gets its own delivery with the same id.

Signature

Every request carries the header:

X-Qapla-Signature: t=1791015120,v1=961fde4b87a60528ed28100be4badc6dcf1d64ce84b82f2a3fe9b077f45c0d2a

• t is the send time, in Unix seconds;
• v1 is the lowercase hex HMAC-SHA256 of the string "<t>.<raw body>", keyed with the endpoint secret as is, whsec_ prefix included;
• during a secret rotation two v1 values arrive, one per valid secret: the request is authentic if at least one matches.

To verify:

1. read the raw body, the bytes as they arrived, before any JSON parsing. Re-encoding the JSON changes whitespace and escapes and the signature no longer matches;
2. extract t and every v1 from the header;
3. reject the request if t differs from your clock by more than 5 minutes (protection against replaying an intercepted request);
4. compute the HMAC-SHA256 of t + "." + body with your secret and compare it with each v1 in constant time (hash_equals, crypto.timingSafeEqual, hmac.compare_digest), never with ==;
5. invalid signature: answer 401 or 403 and drop it. It will not be retried (Retry).

It is the same scheme as the Courier Events API, which uses the signature in the opposite direction.

Verifying the signature

Complete implementations, no external dependencies. All three accept the request if at least one v1 matches, so they keep working during a rotation.

<?php
/**
 * True when at least one v1 in X-Qapla-Signature matches and t is within the tolerance.
 * $rawBody: the request body exactly as received, before any json_decode.
 */
function qaplaSignatureIsValid(string $rawBody, string $header, string $secret, int $tolerance = 300, ?int $now = null): bool
{
    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        $pair = explode('=', trim($part), 2);
        if (count($pair) !== 2) {
            continue;
        }
        if ($pair[0] === 't') {
            $timestamp = $pair[1];
        } elseif ($pair[0] === 'v1') {
            $signatures[] = $pair[1];
        }
    }

    if ($timestamp === null || !ctype_digit($timestamp) || abs(($now ?? time()) - (int) $timestamp) > $tolerance) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }

    return false;
}

// Usage
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_QAPLA_SIGNATURE'] ?? '';
if (!qaplaSignatureIsValid($rawBody, $header, getenv('QAPLA_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody);

const crypto = require('crypto');

// rawBody: Buffer with the request body exactly as received (express.raw, not express.json).
function qaplaSignatureIsValid(rawBody, header, secret, toleranceSec = 300, now = Math.floor(Date.now() / 1000)) {
  let timestamp = null;
  const signatures = [];
  for (const part of String(header || '').split(',')) {
    const i = part.indexOf('=');
    if (i < 0) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === 't') timestamp = value;
    else if (key === 'v1') signatures.push(value);
  }

  if (!/^\d+$/.test(timestamp || '') || Math.abs(now - Number(timestamp)) > toleranceSec) return false;

  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest();
  return signatures.some((signature) => {
    const received = Buffer.from(signature, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

// Usage with Express: the body must stay a Buffer
app.post('/qapla/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!qaplaSignatureIsValid(req.body, req.get('X-Qapla-Signature'), process.env.QAPLA_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(204);
});

import hashlib
import hmac
import time


def qapla_signature_is_valid(raw_body: bytes, header: str, secret: str, tolerance: int = 300, now: float | None = None) -> bool:
    """raw_body: the request body exactly as received (e.g. Flask request.get_data())."""
    timestamp, signatures = None, []
    for part in (header or "").split(","):
        key, sep, value = part.strip().partition("=")
        if not sep:
            continue
        if key == "t":
            timestamp = value
        elif key == "v1":
            signatures.append(value)

    if timestamp is None or not timestamp.isdigit():
        return False
    if abs((time.time() if now is None else now) - int(timestamp)) > tolerance:
        return False

    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, signature) for signature in signatures)

# Usage with Flask
@app.post("/qapla/webhook")
def qapla_webhook():
    if not qapla_signature_is_valid(request.get_data(), request.headers.get("X-Qapla-Signature", ""), os.environ["QAPLA_WEBHOOK_SECRET"]):
        abort(401)
    event = request.get_json()
    return "", 204

Test vector

To check your implementation without waiting for a real send:

Verification must succeed with either secret and fail with any other. t is in the past: for the test, turn off the tolerance check or pass as "now" an instant within 5 minutes of 1791015120 (the samples take a now parameter).

Secret rotation

From the Control Panel you generate a new secret, shown only once. The old one stays valid for 24 hours: in that window every request carries two v1 values, first the new secret's, then the old one's. Afterwards, only the new one.

To rotate without losing deliveries:

1. generate the new secret from the Control Panel;
2. within 24 hours put it in your receiver's configuration in place of the old one. Requests keep passing with either configuration, because they carry both signatures.

Rotate immediately if the secret ended up where it should not (logs, repositories, tickets).

Outbound IPs

The authentication mechanism is the signature, not the source address: always verify X-Qapla-Signature, even if you filter by IP.

If you still need to configure a firewall, the addresses our calls come from are published here, as plain text, one per line: https://cdn.qapla.it/sys/219a40582012cf87b88a782bdfe3a569. The list can change: if you use it, re-read it periodically rather than copying it once.

Request

POST{your url}

• https only, with the server certificate verified: an expired, self-signed or wrong-host certificate is a connection error;
• 10 second timeout for the whole request, connection included;
• no redirects: a 3xx is not followed and counts as a final failure. Configure the final URL;
• the host is resolved on every send and must resolve to public addresses only. If DNS does not answer, we retry; if it resolves to a non-public address, the delivery fails without retry.

Response

Success = any 2xx. The response body is ignored: there is no need to answer {"result":"OK"} as in v1, an empty 204 is fine.

Retry

A retriable outcome puts the delivery back in the queue with a growing delay, with ±20% jitter so that everything does not restart at the same instant. At most 8 attempts, spread over about 22 hours:

Retry-After (seconds or HTTP date) can only lengthen the wait, up to 12 hours: if it says less than the scheduled backoff, the backoff applies. It does not add attempts.

Alerts and switch-off

An endpoint that fails for days is not retried forever:

• once 24 hours have passed since the first failure with no successful delivery, we send a first alert to alertEmail;
• once 3 days have passed, the endpoint becomes disabled, with a second alert;
• the thresholds depend on the time elapsed since the first failure, not on the number of attempts or on how many events arrive in the meantime;
• the count resets on the first 2xx, whether from a delivery or from a test event sent from the Control Panel: once your receiver is fixed, a successful test brings the endpoint back to healthy.

Non-2xx outcomes and connection errors count as failures. A failed test event does not.

When the endpoint is switched off (automatically or by hand):

• deliveries still waiting for a retry move to the failed ones at once, and remain available for replay;
• no events are generated while it is off: nothing piles up while it is down.

It is reactivated from the Control Panel (Channel settings → Updates → “Webhook v2”). It restarts clean, with no flood of old events. Catch up on the gap with GET /v2/shipments?updatedAfter=…, starting from the last update you received.

Replay

Failed deliveries (retries exhausted, rejected with a 4xx, or cut short by the endpoint being switched off) can be sent again from the Control Panel, one by one or by time range, for 30 days from the creation of the delivery. For each delivery the Control Panel shows status, attempts, last HTTP status and error.

A replay puts the delivery back in the queue as new: same id, X-Qapla-Delivery-Attempt starting again from 1, up to 8 attempts again, and the payload rebuilt with the shipment as it is at the new send.

The deliveries list and replay are in Channel settings → Updates → “Webhook v2”.

Migrating from v1

v2 does not replace v1 automatically: it is opt-in, by configuring a v2 endpoint on the channel, because it requires changes to your code. v1 (documentation) stays as it is, with no new features: filters and triggers exist only in v2. There is no end date for v1 yet; it will be announced 12 months in advance.

Suggested procedure

1. build the v2 receiver: signature check, deduplication on id, discard rule on statusDate, fast 2xx answer;
2. test it with the test vector;
3. put it in production next to the v1 receiver, on a different URL;
4. create the v2 endpoint from the Control Panel and store the secret: from here v1 stops for the channel;
5. send a test event and check the outcome;
6. catch up on any update missed during the switch with GET /v2/shipments?updatedAfter=….

Examples

Open points

Contact: tech@qapla.it