Webhookuri

Evenimente

Abonați-vă publicând channels.webhooks[] în configurația magazinului dumneavoastră (un id, un url și events). URL-ul trebuie să fie https public; adresele private, loopback și interne sunt refuzate la salvarea configurației și din nou la trimitere.

Corpul

Corpul este JSON canonic (RFC 8785) și identic octet cu octet la fiecare încercare. data.order este documentul order.v1 semnat complet; data.fromStatus există doar pe 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"
}

Anteturi

Fiecare livrare poartă cinci anteturi. Deduplicați după CutOptim-Event-Id: o reîncercare și o retrimitere îl repetă, în timp ce CutOptim-Delivery-Id diferă.

Verificarea semnăturii

Semnătura este t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Acceptați livrarea când orice valoare v1 se potrivește cu unul dintre secretele dumneavoastră, iar t se află la cel mult 300 secunde de ceasul dumneavoastră; comparați în timp constant. Verificați octeții bruți înainte să-i parsați: un framework care parsează și reserializează corpul îl modifică, iar toate verificările eșuează.

Cele două receptoare de mai jos sunt exemplele de referință, neschimbate: Node 18+ doar cu node:crypto și PHP 7.4+ fără Composer. Ambele citesc secretul din 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']]);

Reîncercări, dead letters și retrimitere

Un răspuns non-2xx, un timeout și o redirecționare sunt încercări eșuate. O livrare este încercată de 6 ori în total, cu așteptări crescânde; după ultimul eșec devine dead letter. Un URL care se rezolvă la o adresă privată este dead letter imediat. Serverul dumneavoastră poate citi jurnalul livrărilor și poate cere o retrimitere cu cheia secretă (/cfg/v1/admin/deliveries); o retrimitere păstrează id-ul evenimentului.

Comenzi de test

O comandă plasată cu o cheie de test nu pune în coadă niciun webhook și niciun e-mail: ERP-ul dumneavoastră și cumpărătorii nu văd niciodată traficul de test.