Webhooks publics : poussez les événements de commandes, d’expéditions et de factures vers votre propre système

Abonnez-vous aux événements Docklify — commande créée, commande honorée, expédition remise au transporteur, facture émise, livraison terminée — et recevez-les en envois HTTPS signés sur votre propre endpoint, avec événements de test, réessais automatiques et journal de livraison.

Les webhooks publics transforment ce qui se passe dans Docklify en messages vers votre propre système. Dès qu’une commande est créée, qu’une expédition est remise au transporteur ou qu’une facture est émise, Docklify envoie un post HTTPS à une adresse que vous contrôlez. Usages typiques : synchroniser les commandes vers votre ERP ou votre comptabilité, prévenir vos clients avec vos propres mots, alimenter vos tableaux de bord, ou déclencher un processus en aval sans interroger une API.

Événements auxquels vous pouvez vous abonner#

• order.created : une commande de vente est créée (saisie manuelle, portail client ou conversion CRM).
• order.allocated : une commande est allouée et le stock est réservé.
• order.fulfilled : une commande est entièrement honorée ; inclut le numéro de suivi et le transporteur.
• order.cancelled : une commande est annulée ; inclut le code de motif.
• order.delivered : une commande est marquée comme livrée.
• shipment.fulfilled : une expédition WMS est remise au transporteur ; inclut le numéro de suivi.
• receipt.completed : une réception entrante est terminée, toutes les lignes reçues.
• inventory.adjusted : le stock est ajusté directement sur un emplacement.
• invoice.issued : une facture client est générée. Les nouvelles factures sont en brouillon ; le champ de statut indique le statut actuel.
• delivery.completed : une livraison du dernier kilomètre est signée et terminée, preuve de livraison capturée.
• test.ping : l’événement de test. Envoyez-le à tout moment pour vérifier que votre endpoint répond et que la vérification de signature fonctionne.

Créer un abonnement#

1. Ouvrez Integration → Webhooks et cliquez sur Nouvel abonnement.
2. Nom : donnez-lui un nom que votre équipe reconnaîtra, par exemple « Synchro ERP ».
3. URL : l’adresse https de votre serveur qui recevra les événements. Elle doit utiliser https et se résoudre en adresse publique : les adresses privées, locales ou de bouclage sont refusées.
4. Événements : cochez les événements voulus. Vous pourrez changer la sélection à tout moment.
5. Enregistrez, puis copiez le secret de signature — il commence par whsec_. Conservez-le dans la configuration de votre serveur ; il sert à vérifier que les livraisons viennent bien de Docklify. Vous pourrez le revoir, ou le renouveler, sur la page Webhooks à tout moment.

Ce que votre récepteur doit faire#

Chaque livraison est un post HTTPS avec un corps JSON — l’enveloppe. L’enveloppe dit ce qui s’est passé (type), quand (created_at), et les détails sont dans data :

{
  "id": "<event id>",
  "type": "order.fulfilled",
  "created_at": "2026-10-20T12:00:00.000Z",
  "organization_id": "<your organization id>",
  "data": {
    "order_id": "<order id>",
    "order_no": "SO-1001",
    "status": "fulfilled",
    "tracking_number": "<tracking number>",
    "carrier_code": "ups"
  }
}

• Dédupliquez par id : la livraison est « au moins une fois ». Les réessais et les renvois manuels réutilisent le même id d’événement : gardez les id traités et ignorez les doublons.
• Répondez 2xx, et répondez vite : tout statut 2xx compte comme un succès. Les livraisons expirent après 10 secondes ; si votre traitement est lent, stockez d’abord l’événement, répondez 200, puis traitez-le.
• Tout le reste compte comme un échec : un statut non 2xx, une redirection (le 3xx n’est pas suivi), un dépassement de délai ou une adresse injoignable — tout déclenche les réessais automatiques décrits plus bas.

Vérifier la signature#

N’importe qui connaissant votre URL pourrait y envoyer de faux événements : chaque livraison est donc signée — vérifiez la signature avant de faire confiance aux données. La spécification complète (noms d’en-têtes, algorithme exact, exemples d’une ligne en Node et Python) se trouve dans la documentation API, section Webhooks. Les points essentiels :

• Chaque livraison porte l’en-tête X-Docklify-Signature, de la forme t=<secondes unix>,v1=<hex>. La même livraison porte aussi X-Docklify-Event (le type d’événement) et X-Docklify-Delivery (l’id de livraison).
• v1 est le HMAC-SHA256 en hex de la chaîne « <t>.<corps brut> », avec votre secret de signature comme clé.
• Calculez toujours sur le corps brut de la requête, exactement comme reçu. Ne parsez jamais le JSON pour le resérialiser : les espaces et l’ordre des clés changent, et la signature ne correspondra plus.
• Si la signature ne correspond pas, ne traitez pas l’événement.

Envoyer un événement de test#

1. Dans Integration → Webhooks, ouvrez votre abonnement et choisissez Envoyer un événement de test.
2. Docklify livre aussitôt un test.ping à votre URL. Les événements de test peuvent être envoyés à n’importe quel abonnement, même si test.ping n’est jamais dans sa liste d’événements.
3. Vérifiez le journal de livraison : une ligne livrée, plus une signature vérifiée côté serveur, et vous êtes prêt pour les événements réels.

Journal de livraison et dépannage#

Chaque livraison est consignée dans le journal de livraison (Integration → Webhooks → Livraisons) : le type d’événement, le statut (en attente, livré ou échoué), le nombre de tentatives, le dernier code HTTP et la dernière erreur, et l’heure du prochain réessai. Une livraison échouée est réessayée automatiquement après 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures — six tentatives au total. Après la dernière, elle reste échouée jusqu’à un renvoi manuel depuis le journal ; le renvoi réutilise le même id d’événement, donc votre déduplication reste sûre.

• Adresse injoignable : votre serveur est arrêté, l’URL est fausse ou le nom ne se résout pas en adresse publique. Corrigez l’endpoint, puis renvoyez depuis le journal.
• Problèmes de certificat : un certificat TLS expiré ou auto-signé fait échouer la livraison. Utilisez un certificat valide d’une autorité publique.
• Réponse non 2xx : votre récepteur a planté ou rejeté l’événement. Lisez le code et l’erreur dans le journal, corrigez la cause, puis renvoyez.
• Délai dépassé : votre récepteur a mis plus de 10 secondes. Répondez 2xx d’abord et faites le gros du travail en arrière-plan.
• Signature non concordante de votre côté : le plus souvent un corps resérialisé, ou un ancien secret encore utilisé après un renouvellement — voir Vérifier la signature ci-dessus.

Mettre un abonnement en pause et renouveler le secret#

• Pause : mettez l’abonnement en pause sur la page Webhooks. Pendant la pause, Docklify ne lui livre pas de nouveaux événements. Reprendre à tout moment — la pause est le moyen sûr de mettre un endpoint hors ligne pour maintenance.
• Renouveler le secret : si un secret a pu fuiter, ou si un collègue qui le connaissait est parti, renouvelez-le sur la page de l’abonnement. Après le renouvellement, les livraisons sont signées avec le nouveau secret uniquement : mettez votre serveur à jour au même moment — un récepteur avec l’ancien secret rejettera les nouvelles livraisons.