Webhooks : recevoir automatiquement les mises à jour de commande

Comment fonctionnent les webhooks ?

Vous nous donnez une URL https de votre propre serveur. À chaque événement, nous y envoyons une requête POST avec un message JSON. Votre serveur répond avec un statut 2xx, et nous savons alors que le message est arrivé.

• X-Printen-Event : le type d’événement, par exemple order.shipped.
• X-Printen-Delivery : un id de cette livraison. Pratique dans vos journaux.
• X-Printen-Timestamp : l’heure d’envoi, en secondes depuis 1970 (temps Unix).
• X-Printen-Signature : la signature (v1= suivi d’un code hexadécimal), qui vous permet de vérifier que le message vient bien de nous.

Comment ajouter un endpoint ?

1. 1

   Ouvrez l’onglet

   Dans votre tableau de bord, allez dans Webhooks.

2. 2

   Saisissez votre URL

   Dans URL (https), saisissez l’adresse de votre propre serveur, par exemple https://votredomaine.fr/printen-webhook.

3. 3

   Choisissez les événements

   Cochez les événements que vous voulez recevoir. Par défaut, order.shipped, order.payment_failed et order.awaiting_funds sont cochés.

4. 4

   Ajoutez le webhook

   Cliquez sur Ajouter un webhook. Le secret s’affiche, avec le message Conservez ce secret maintenant. Il ne s’affichera qu’une fois.

5. 5

   Conservez le secret

   Placez aussitôt le secret dans la configuration de votre serveur, par exemple dans une variable d’environnement. Vous en avez besoin pour vérifier la signature.

Vous pouvez aussi ajouter un endpoint via l’API avec POST /webhooks. Si vous omettez events ou envoyez une liste vide, vous recevez tous les événements. Le secret ne figure que dans cette réponse.

curl -X POST https://www.printen.eu/api/reseller/v1/webhooks \
  -H "Authorization: Bearer prk_live_..." -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/printen-webhook","events":["order.shipped","order.delivered"]}'

{
  "data": {
    "id": "WEBHOOK_ID",
    "url": "https://example.com/printen-webhook",
    "events": ["order.shipped", "order.delivered"],
    "allEvents": false,
    "active": true,
    "createdAt": "2026-10-10T09:00:00.000Z",
    "updatedAt": "2026-10-10T09:00:00.000Z",
    "secret": "WEBHOOK_SECRET"
  }
}

• L’URL doit utiliser https et être accessible publiquement. Les adresses comme localhost, les adresses de réseau interne et les noms se terminant par .local, .internal ou .lan sont refusés.
• Vous pouvez avoir au maximum 10 endpoints par compte.
• Chaque endpoint a son propre secret.

Quels événements existent ?

À quoi ressemble un message ?

Chaque message a la même structure. Voici un exemple de order.shipped.

{
  "id": "EVENT_ID",
  "type": "order.shipped",
  "created": "2026-10-10T14:32:05.000Z",
  "data": {
    "order": {
      "id": "ORDER_ID",
      "orderNumber": "RS-3F9A1C7B2E",
      "externalOrderId": "1001",
      "externalOrderNumber": "1001",
      "state": "SUBMITTED",
      "status": "SHIPPED",
      "tracking": {
        "code": "3SABCD1234567",
        "url": "https://example.com/track/3SABCD1234567"
      },
      "items": [
        {
          "productId": "PRODUCT_ID",
          "name": "Poster",
          "quantity": 1,
          "options": { "size": "A2" }
        }
      ]
    }
  }
}

Comment vérifier la signature ?

N’importe qui peut envoyer une requête à votre URL. Vérifiez donc la signature de chaque message avant d’agir. La signature est un HMAC-SHA256 calculé avec le secret de votre endpoint.

1. 1

   Lisez les en-têtes

   Récupérez X-Printen-Timestamp et X-Printen-Signature dans la requête.

2. 2

   Vérifiez l’heure

   Rejetez le message si l’horodatage s’écarte de plus de 5 minutes (300 secondes) de l’heure actuelle. Personne ne peut ainsi rejouer un ancien message.

3. 3

   Calculez la signature attendue

   Calculez un HMAC-SHA256 avec votre secret sur le texte timestamp.rawBody : l’horodatage, un point puis le corps brut. Ajoutez v1= devant.

4. 4

   Comparez en sécurité

   Comparez le résultat à X-Printen-Signature avec une comparaison à temps constant. S’ils ne correspondent pas, répondez 401 et ne traitez rien.

import crypto from 'node:crypto';

export function verifyPrintenWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-printen-timestamp'];
  const signature = headers['x-printen-signature'] || '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'v1=' + crypto.createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`).digest('hex');
  return signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

<?php
function verify_printen_webhook(string $rawBody, string $timestamp, string $signature, string $secret): bool {
    if (abs(time() - (int) $timestamp) > 300) return false;
    $expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, $signature);
}

import hashlib, hmac, time

def verify_printen_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Piège : vérifiez sur le corps brut

La signature est calculée sur le corps exactement tel que nous l’envoyons, octet par octet. Beaucoup de frameworks lisent automatiquement le corps comme du JSON. Si vous reconvertissez ensuite ce JSON en texte, les espaces, l’ordre ou certains caractères peuvent différer légèrement, et la signature ne correspond plus.

import express from 'express';
import { verifyPrintenWebhook } from './verify-printen-webhook.js';

const app = express();

// express.raw (not express.json) keeps the body exactly as it was sent
app.post('/printen-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verifyPrintenWebhook(rawBody, req.headers, process.env.PRINTEN_WEBHOOK_SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(rawBody);
  await saveEventForProcessing(event); // store first, process later
  res.status(200).send('ok');
});

• PHP : lisez le corps avec file_get_contents("php://input"), pas avec $_POST.
• Python (Flask) : utilisez request.get_data() pour les octets bruts, pas request.json.
• Next.js (App Router) : utilisez await request.text() et seulement ensuite JSON.parse.

Et si votre endpoint ne répond pas ?

Une livraison réussit si vous répondez en moins de 10 secondes avec un statut 2xx. Tout autre résultat compte comme un échec : un délai dépassé, un statut d’erreur, mais aussi une redirection (3xx). Nous réessayons alors selon ce calendrier.

Après la dixième tentative, nous abandonnons pour cet événement. Votre endpoint n’est jamais désactivé automatiquement : nous continuons d’envoyer les nouveaux événements.

Traiter les événements en double ou dans le désordre

À cause des répétitions, un même événement peut arriver plusieurs fois, et les événements peuvent arriver dans un autre ordre que celui où ils se sont produits. Concevez votre traitement en conséquence.

• Dédoublonnez sur `id` : enregistrez l’id de chaque événement traité. Si le même id revient, répondez 2xx et ne faites rien d’autre.
• Surveillez l’ordre avec `created` : si vous avez déjà traité un événement plus récent pour cette commande, n’écrasez pas un statut récent par un plus ancien.
• Ne faites jamais reculer un statut : si order.shipped arrive après order.delivered, laissez la commande au statut livrée.
• En cas de doute, consultez la commande : GET /orders/{id} vous donne toujours l’état actuel.

Comment tester votre webhook ?

1. 1

   Préparez votre endpoint

   Assurez-vous que votre URL est accessible publiquement en https. Si vous travaillez en local, utilisez un service de tunnel qui redirige une URL https publique vers votre ordinateur.

2. 2

   Ajoutez l’endpoint

   Ajoutez-le dans Webhooks et cochez order.created, order.submitted et order.cancelled (ou omettez les événements via l’API pour tout recevoir).

3. 3

   Passez une commande de test

   Passez une commande via l’API avec une clé de test (prk_test_). En quelques minutes, vous recevez order.created et order.submitted (avec test dans data).

4. 4

   Annulez la commande de test

   Annulez la commande avec POST /orders/{id}/cancel. Vous recevez alors order.cancelled.

5. 5

   Vérifiez vos journaux

   Vérifiez que la signature était correcte, que vous avez répondu 2xx et qu’un message répété avec le même id a bien été ignoré.

Résoudre les problèmes