Webhooks ou polling ? Un suivi de commandes capable de se rétablir

Utilisez les webhooks pour les changements courants et gardez des consultations d’état pour vérifier la cohérence de vos dossiers. Sans récepteur public fiable, commencez par des requêtes groupées.

Une commande peut finir pendant un redémarrage et un événement arriver deux fois si son accusé de réception se perd. Le suivi doit gérer les deux sans afficher d’anciennes informations ni appliquer deux fois une mise à jour.

Un rôle pour chaque méthode

Polling : demander l’état actuel

action=status renvoie l’état au moment de la consultation. Regroupez jusqu’à 100 IDs. Interroger plus souvent multiplie les requêtes, même sans changement.

Webhooks : recevoir les changements choisis

NotPanel envoie des événements à votre URL HTTPS. Ils ne consomment pas le quota de requêtes status du client, mais le récepteur doit être dimensionné et surveillé.

Rapprochement : retrouver ce qui manque

Après une panne ou devant un dossier ancien, consultez les commandes concernées. Un événement peut être manqué ; les tentatives sont limitées et la livraison n’est pas garantie.

Ce que l’API NotPanel envoie

Ajoutez un endpoint sur la page API de votre dashboard ou avec webhook.add : une URL HTTPS publique et les événements utiles, comme order.processing, order.in_progress, order.completed, order.partial, order.canceled, order.cancel_refused, refill.completed et refill.rejected ; la référence des webhooks les liste tous. Conservez le secret : il n’est affiché qu’une fois et webhook.list ne le renvoie jamais. Consultez vos endpoints avec webhook.list, envoyez un ping de test avec webhook.test et supprimez un endpoint avec webhook.remove.

Chaque livraison transporte un seul événement dans une courte enveloppe : id, type, schema_version, created_at, sequence et data. data.order contient les mêmes champs qu’une réponse action=status. L’exemple abrégé montre la forme, pas une commande réelle.

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

Lisez le type d’événement dans le corps vérifié. X-Webhook-Event est aussi envoyé, mais il n’est pas signé. Les endpoints créés dans le dashboard et via l’API reçoivent la même enveloppe.

Recevoir les événements avec fiabilité

1. Conservez le corps brut. Vérifiez X-Webhook-Signature avec le secret et X-Webhook-Timestamp, puis appliquez votre tolérance temporelle. Reconstruire le contenu peut modifier les octets signés.
2. Journalisez X-Webhook-Delivery-Id pour suivre les tentatives ; il reste identique à chaque nouvelle tentative de cette livraison. Enregistrez l’événement vérifié avant de répondre 2xx ; si vous ne pouvez pas l’accepter correctement, laissez la nouvelle tentative se produire.
3. Traitez chaque id d’événement une fois et conservez ce suivi après redémarrage, avec la mise à jour de commande. Le même id d’événement parvient à chaque endpoint abonné.
4. Faites les tâches lentes après acceptation. La signature prouve l’authenticité, pas l’ordre d’arrivée. Utilisez sequence pour ordonner les événements et, si un événement tardif contredit un état récent, consultez status avant de le remplacer.

Guide de vérification des signatures

Quand le récepteur est indisponible

Un timeout (10 secondes) ou une réponse hors 2xx est une tentative échouée. NotPanel essaie chaque livraison jusqu’à 8 fois en 24 heures : immédiatement, puis 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures, 12 heures et 24 heures après l’événement. Il suspend l’endpoint après 50 échecs d’affilée ou 3 jours sans succès, et prévient le titulaire du compte. Une livraison réussie remet le compteur à zéro. Surveillez webhook.list : le silence ne prouve pas l’absence de changements.

Vérifiez périodiquement les commandes en attente ou anciennes par lots de 100 IDs maximum, en respectant les en-têtes et limites. Après réparation, reprenez l’endpoint dans la section webhooks de la page API de votre dashboard, ce qui remet son compteur d’échecs à zéro. Vous pouvez aussi le supprimer avec webhook.remove, ajouter de nouveau l’URL HTTPS réparée avec webhook.add et les événements souhaités, conserver le nouveau secret en lieu sûr et configurer le récepteur pour le vérifier. L’API publique ne propose pas d’action pour reprendre un endpoint. Les livraisons en attente au moment de la suspension ne sont pas rejouées : rapprochez les états manqués avec status.

Testez au-delà d’une livraison réussie

Utilisez des messages fictifs et votre propre secret de test ; aucune commande réelle n’est nécessaire.

• Deux envois identiques doivent produire une seule mise à jour.
• Le même événement livré deux fois, avec un redémarrage entre les deux, doit toujours être reconnu.
• Un octet modifié ou une date ancienne doit être refusé selon votre politique.
• Après une panne et un événement tardif, status doit rétablir la vue actuelle.

Choisir les événements, vérifier les secrets et confirmer rapidement figurent aussi dans les recommandations de GitHub. Les en-têtes, formats et limites présentés ici restent ceux de NotPanel.

Questions fréquentes

Puis-je utiliser uniquement le polling ?

Oui. Regroupez les consultations et adaptez leur fréquence au volume et aux limites. Les webhooks ne sont pas obligatoires pour créer ou suivre une commande.

Les webhooks arrivent-ils immédiatement et une seule fois ?

Non. Ils peuvent être retardés ou répétés. Vérifiez chaque livraison, traitez chaque événement une fois et conservez les consultations d’état pour récupérer les lacunes.

Quels en-têtes vérifier ?

X-Webhook-Signature et X-Webhook-Timestamp, puis lisez id, type et data dans le corps vérifié. Utilisez X-Webhook-Delivery-Id uniquement pour suivre les tentatives.

Un webhook protège-t-il un add incertain ?

Ce sont deux sujets distincts. Réessayez l’add avec son request_id initial et ses paramètres inchangés, puis enregistrez l’ID de commande retrouvé.

Références : contrat des webhooks · état de commande · récupération après timeout.