Webhooks

Au lieu d'interroger l'API, enregistrez un endpoint HTTPS : Nembol vous envoie un événement en POST dès qu'il se passe quelque chose : une nouvelle commande arrive depuis n'importe quel canal, le stock change, une annonce passe en ligne ou tombe en erreur.

Créez des endpoints dans le tableau de bord (Paramètres → Développeurs → Webhooks) ou via l'API. Chaque endpoint possède un secret de signature, affiché une seule fois à la création.

La livraison

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Nembol-Webhooks/1.0 (+https://developers.nembol.com/docs/webhooks)
X-Nembol-Event-Id: evt_2c91…
X-Nembol-Signature: t=1784900412,v1=5257a869e7…

{
  "id": "evt_2c91…",
  "type": "order.created",
  "api_version": "2026-07-24",
  "store_id": "5f2a…",
  "account_id": "acct_66f0a1",
  "created_at": "2026-07-24T16:03:12Z",
  "data": {
    "object": { "id": "ord_…", "channel": "etsy", "total": "49.90", "currency": "USD" }
  }
}

account_id n'est présent que pour les partenaires, sur chaque événement de l'une de leurs entreprises (livraisons comme GET /events, operation.completed compris) : il indique à quelle entreprise appartient l'événement (le même identifiant que dans GET /accounts). Les événements de votre propre boutique ne l'ont pas. Basez votre routage dessus.

Chaque livraison porte User-Agent: Nembol-Webhooks/1.0 et l'identifiant de l'événement dans X-Nembol-Event-Id. Fiez-vous à la signature, pas à ces en-têtes : ils servent à vos journaux et à vos règles de pare-feu. Une livraison est envoyée une fois par endpoint (elle n'est répétée que lors des relances après une réponse non 2xx, avec le même identifiant d'événement).

data.object est la ressource complète telle qu'elle est au moment de la livraison de l'événement (ou de sa lecture via GET /events), et non une copie figée au moment de la modification. Ce qui a changé se trouve dans data lui-même : par ex. data.status et data.previous_status sur listing.status_changed. Si la ressource a de nouveau changé entre-temps, data.object montre déjà l'état le plus récent et un événement plus récent suit ; ordonnez vos mises à jour selon le created_at de l'événement.

Le contrat (à lire deux fois)

• Au moins une fois : le même événement peut être livré plusieurs fois. Dédupliquez par event.id.
• Aucune garantie d'ordre : les événements peuvent arriver dans le désordre. Utilisez created_at (ou relisez la ressource) plutôt que de supposer une séquence.
• Chaque événement est livré, quelle que soit la partie de Nembol qui l'a produit (appel API, tableau de bord, synchronisation des commandes, webhook d'un canal). Si la livraison d'un événement n'a pas pu être mise en file à sa création, Nembol la met en file dans les quelques minutes qui suivent (événements de moins de 24 heures) : il arrive en retard, mais il arrive toujours. Un endpoint ne reçoit que les événements créés après lui. GET /events reste la voie de réconciliation.
• Types inconnus : de nouveaux types d'événements sont ajoutés au fil du temps. Ignorez les types que vous ne traitez pas, et répondez quand même 2xx.
• Répondez vite avec un 2xx : en moins de 10 secondes, sinon la livraison est considérée comme échouée. Faites le vrai travail de façon asynchrone : mettez en file, puis renvoyez 200.
• Vérifiez la signature avant de vous fier à quoi que ce soit : vérifier les signatures.

Relances

Les livraisons échouées (réponse non 2xx, délai dépassé, erreur de connexion) sont relancées avec un délai exponentiel : 1m → 5m → 30m → 2h → 12h (environ 15 heures), puis la livraison est marquée comme échouée. Si un endpoint continue d'échouer, il est désactivé automatiquement et le propriétaire de la boutique est averti dans le tableau de bord et par e-mail. Chaque tentative est visible dans le journal des livraisons du tableau de bord, avec un renvoi manuel.

Vous avez manqué toute une période ? Réconciliez avec l'API du journal des événements : GET /events?created_after=… renvoie les événements des 30 derniers jours.

Dernière mise à jour le 20 octobre 2026