Webhooks

Événements

Abonnez-vous en publiant channels.webhooks[] dans la configuration de votre boutique (un id, une url et les events). L’URL doit être un https public ; les adresses privées, de bouclage et internes sont refusées à l’enregistrement de la configuration, puis de nouveau à l’envoi.

Le corps

Le corps est du JSON canonique (RFC 8785) et identique octet pour octet à chaque tentative. data.order est le document order.v1 signé complet ; data.fromStatus n’existe que sur order.status_changed.

{
  "createdAt": "2026-10-19T09:30:00.000Z",
  "data": {
    "fromStatus": "received",
    "order": {
      "…": "order.v1"
    },
    "orderId": "<order id>",
    "status": "confirmed"
  },
  "id": "<event id>",
  "schemaVersion": 1,
  "tenantId": "<tenant id>",
  "type": "order.status_changed"
}

En-têtes

Chaque envoi porte cinq en-têtes. Dédupliquez sur CutOptim-Event-Id : une nouvelle tentative et un réenvoi le répètent, alors que CutOptim-Delivery-Id diffère.

Vérifier la signature

La signature est t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Acceptez l’envoi lorsqu’une valeur v1 correspond à l’un de vos secrets et que t est à moins de 300 secondes de votre horloge ; comparez en temps constant. Vérifiez les octets bruts avant de les analyser : un framework qui analyse puis resérialise le corps le modifie, et toutes les vérifications échouent.

Les deux récepteurs ci-dessous sont les exemples de référence, tels quels : Node 18+ avec node:crypto uniquement, et PHP 7.4+ sans Composer. Les deux lisent le secret dans CUTOPTIM_WEBHOOK_SIGNING.

configurator/adapters/reference/node/example-server.mjs

// example-server.mjs - a webhook endpoint on node:http, to read and adapt.   CUTOPTIM_WEBHOOK_SIGNING=whsec_... node example-server.mjs
// (whsec_REPLACE_ME is a placeholder: the real secret comes from the CutOptim admin route.)
import { createServer } from 'node:http';
import { createWebhookReceiver } from './cutoptim-verify.mjs';

const secret = process.env.CUTOPTIM_WEBHOOK_SIGNING;
if (!secret) { console.error('set CUTOPTIM_WEBHOOK_SIGNING (whsec_REPLACE_ME is a placeholder)'); process.exit(1); }

const receive = createWebhookReceiver({
  secrets: [secret],
  async onEvent(event) {
    // event.type === 'order.created'; event.data.order is the signed order document. Store it in YOUR order table here,
    // keyed by event.data.orderId, in the same transaction that records the event id as seen.
    console.log('order.created', event.data.orderId);
  },
});

createServer(async (req, res) => {
  if (req.method !== 'POST') { res.writeHead(405).end(); return; }
  const chunks = []; let size = 0;
  for await (const c of req) { size += c.length; if (size > 2_000_000) { res.writeHead(413).end(); return; } chunks.push(c); }
  const out = await receive({ rawBody: Buffer.concat(chunks), headers: req.headers });   // the RAW bytes, not parsed JSON
  res.writeHead(out.status, { 'Content-Type': 'application/json' }).end(JSON.stringify({ result: out.reason }));
}).listen(Number(process.env.PORT ?? 8787));

configurator/adapters/reference/php/example-webhook.php

<?php
/**
 * example-webhook.php - a webhook endpoint in plain PHP, to read and adapt.
 * CUTOPTIM_WEBHOOK_SIGNING=whsec_... is read from the environment (whsec_REPLACE_ME is a placeholder; the real secret comes from the
 * CutOptim admin route). Replace MemorySeen with a table that has a UNIQUE key on the event id.
 */
require __DIR__ . '/CutOptimVerify.php';

use CutOptim\CutOptimVerify;
use CutOptim\MemorySeen;

$secret = getenv('CUTOPTIM_WEBHOOK_SIGNING');
if ($secret === false || $secret === '') {
    http_response_code(500);
    exit('CUTOPTIM_WEBHOOK_SIGNING is not set');
}

$rawBody = file_get_contents('php://input');   // the RAW bytes, not decoded JSON
$headers = function_exists('getallheaders') ? getallheaders() : [];
$out = CutOptimVerify::handleWebhook($rawBody, $headers, [$secret], new MemorySeen(), static function (array $event): void {
    // $event['type'] === 'order.created'; $event['data']['order'] is the signed order document. Store it in YOUR order table
    // keyed by $event['data']['orderId'], in the same transaction that records the event id as seen.
});

http_response_code($out['status']);
header('Content-Type: application/json');
echo json_encode(['result' => $out['reason']]);

Nouvelles tentatives, dead letters et réenvoi

Une réponse non 2xx, un délai dépassé et une redirection sont des tentatives échouées. Un envoi est essayé 6 fois au total, avec des attentes croissantes ; après le dernier échec, il devient une dead letter. Une URL qui se résout vers une adresse privée est immédiatement une dead letter. Votre serveur peut lire le journal des envois et demander un réenvoi avec la clé secrète (/cfg/v1/admin/deliveries) ; un réenvoi conserve l’identifiant d’événement.

Commandes de test

Une commande passée avec une clé de test ne met en file aucun webhook ni e-mail : votre ERP et vos clients ne voient jamais le trafic de test.