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

Ce guide concerne les inscriptions via webhook.add : URL HTTPS publique et événements pris en charge, dont order.processing, order.in_progress, order.completed, order.partial, order.refunded et order.refill_completed. Conservez le secret ; webhook.list ne le renvoie pas. Consultez l’état et les échecs avec webhook.list et supprimez une inscription avec webhook.remove.

Les livraisons API contiennent events, même avec un seul événement. Chaque élément possède id, event, timestamp et data ; deliveryId identifie la livraison. L’exemple abrégé est illustratif. Ses anciennes dates ne permettent pas de tester la tolérance temporelle.

{
  "events": [
    {
      "id": "EXAMPLE_EVENT_ID",
      "event": "order.completed",
      "timestamp": 1700000000,
      "data": { "order": 7001, "status_key": "completed" }
    }
  ],
  "timestamp": 1700000001,
  "deliveryId": "EXAMPLE_DELIVERY_ID"
}

Lisez le nom de l’événement dans le corps vérifié : les lots API ne nécessitent pas X-Webhook-Event. Les webhooks créés dans le dashboard utilisent un autre format à événement unique ; ces formats ne sont pas interchangeables.

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. Comparez X-Webhook-Delivery-Id au deliveryId du corps signé. Enregistrez la livraison avant de répondre 2xx ; si vous ne pouvez pas l’accepter correctement, laissez la nouvelle tentative se produire.
3. Traitez chaque events[].id une fois et conservez ce suivi après redémarrage, avec la mise à jour de commande. Un événement peut arriver par plusieurs endpoints.
4. Faites les tâches lentes après acceptation. La signature prouve l’authenticité, pas l’ordre d’arrivée. 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 ou une réponse hors 2xx compte comme un échec. NotPanel réessaie avec des délais croissants et suspend l’endpoint API après 10 échecs consécutifs ; 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 d’un récepteur suspendu, vérifiez que son inscription est active. Ne présumez pas que les anciens échecs seront tous rejoués automatiquement.

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.
• Un événement dans deux lots et un redémarrage ne doivent pas le dupliquer.
• 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 comparez X-Webhook-Delivery-Id au deliveryId du corps vérifié et traitez son tableau events.

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.