Webhooks dans l'API Acheteur

​

Configurer un endpoint

• l’URL HTTPS qui doit recevoir les livraisons,
• lesquels des trois événements vous voulez (workorder.create, workorder.status_update, workorder.new_note), et
• si l’endpoint sert aux tests ou à la production.

​

Événements

• workorder.create se déclenche à chaque création, quel qu’en soit l’auteur : votre propre POST /v1/buyer/work_order/work_orders, un utilisateur des applications web ou mobile OpenWrench, un calendrier de maintenance planifiée, une visite d’inspection de site, ou un fournisseur qui ouvre un bon de travail sur l’un de vos emplacements (SupplierInitiatedPendingApproval). La charge utile porte le statut initial, ce qui vous permet de distinguer une demande de service en attente d’approbation d’un bon de travail réparti dès sa création.
• workorder.status_update se déclenche à chaque transition du modèle de statut, pour les statuts détenus par l’un ou l’autre côté. Les modifications qui ne touchent pas status (un changement de priorité, une nouvelle date d’achèvement estimée, une réaffectation alors que le bon de travail est encore en attente de confirmation) n’en émettent pas. Quand un bon de travail passe d’un fournisseur à un autre, vous pouvez recevoir une mise à jour intermédiaire dont le newStatus est Rejected, qui clôt l’affectation précédente, suivie de la mise à jour vers le nouveau statut.
• workorder.new_note se déclenche pour les notes du fil racine acheteur–fournisseur venant de l’un ou l’autre côté, y compris les notes publiées par votre propre intégration, les envois groupés de photos et la note jointe à une action de statut. Les notes internes des fournisseurs et les fils de sous-traitance n’émettent jamais d’événement.

​

Charge utile de la livraison

​

Événements de création et de statut

{
  "event_type": "workorder.status_update",
  "data": {
    "workOrderId": 9001,
    "location": "Store 1204 - Denver",
    "oldStatus": "TechScheduled",
    "newStatus": "WaitingForReview",
    "changedBy": "Sam Rivera",
    "changedAt": "2026-08-21T09:05:22.000-07:00"
  }
}

​

Événements de note

{
  "event_type": "workorder.new_note",
  "data": {
    "workOrderId": 9001,
    "newNote": "Access code for the back door is 4417.",
    "addedBy": "Sam Rivera",
    "addedAt": "2026-08-21T09:05:22.000-07:00"
  }
}

​

Vérifier les livraisons

​

Réponse, nouvelles tentatives et doublons

• Accusez réception rapidement. Renvoyez un 2xx dès que vous avez stocké l’événement, et effectuez le travail de suivi (récupération du bon de travail, mise à jour de votre système) de manière asynchrone. Une réponse autre que 2xx ou un dépassement de délai compte comme une livraison échouée.
• Les livraisons échouées sont retentées par la passerelle selon un calendrier d’attente croissante. Rendez votre gestionnaire idempotent pour qu’une nouvelle tentative après un succès partiel soit sans effet.
• Les livraisons sont au moins une fois. Le même événement peut arriver plus d’une fois, même sans échec de votre côté. Dédoublonnez sur event_type plus workOrderId plus changedAt (ou addedAt pour les notes).
• L’ordre n’est pas garanti. Deux événements pour le même bon de travail peuvent arriver dans le désordre. Ne déduisez pas l’état de la séquence d’événements; récupérez le bon de travail et fiez-vous à son status.
• Les événements périmés sont abandonnés, pas livrés en retard. Un événement qui n’a pas été transmis à la passerelle dans les trois heures suivant le changement est écarté. Après une panne côté OpenWrench, ou si votre endpoint est resté indisponible plus longtemps que la fenêtre de nouvelles tentatives, réconciliez en sondant GET /v1/buyer/work_order/work_orders?statusChangedAt=... sur la période manquée.

​

Réagir à un événement

# Fetch the work order named in the event
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_orders/9001"

​

Assembler le tout

1. Enregistrez un endpoint pour workorder.create et workorder.status_update (ajoutez workorder.new_note si vous répliquez la conversation).
2. Sur workorder.create, récupérez le bon de travail et créez l’enregistrement correspondant dans votre système. Si vous répartissez de votre côté, faites un PATCH du supplierFacilityId comme décrit dans Bons de travail.
3. Sur workorder.status_update, récupérez le bon de travail. Quand newStatus vaut WaitingForReview, lancez votre flux de revue et publiez work_reviewed_and_completed ou work_unsatisfactory.
4. Exécutez un sondage périodique sur statusChangedAt comme filet de sécurité pour tout ce que le chemin des webhooks aurait manqué.