Webhooks dans l'API Fournisseur

​

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 signifie « nouveau travail pour vous », et pas seulement « une nouvelle ligne a été créée ». Il se déclenche quand un bon de travail est créé avec votre établissement affecté, quand un acheteur vous réaffecte un bon de travail existant (il entre en PendingConfirmationByServiceProvider), et quand vous ouvrez vous-même un bon de travail à l’initiative du fournisseur (SupplierInitiatedPendingApproval). Un bon de travail créé pour vous mais qui nécessite d’abord l’approbation interne de l’acheteur émet workorder.create lorsqu’il atteint PendingConfirmationByServiceProvider, pas au moment où l’approbateur de l’acheteur le voit pour la première fois.
• workorder.status_update se déclenche quand un bon de travail qui vous est affecté entre en ConfirmedByServiceProvider, TechAssigned, TechScheduled, TechRescheduled, WorkIncompleteWithReason (sauf s’il vient directement de TechWorkingOnSite, ce qui correspond à un check-out), WorkUnsatisfactory, WorkReviewedAndCompleted, CancelledWithReason ou PaymentMade. Cela couvre votre propre acceptation, la planification faite par vos techniciens dans les applications OpenWrench, et les décisions de l’acheteur sur votre travail. Les statuts de pièces, TechEnRoute, TechWaitingOnSite, TechWorkingOnSite, WaitingForReview et les statuts de devis et de proposition n’émettent pas d’événement.
• 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. Vos notes internes et les fils des bons de travail que vous sous-traitez n’émettent jamais d’événement.

• Réaffectation à un autre fournisseur. Si l’acheteur déplace un bon de travail vers un autre fournisseur, il disparaît simplement de votre file. Réconciliez avec GET /v1/supplier/work_order/work_orders si cela vous importe.
• Bons de travail que vous pouvez seulement consulter. Si votre établissement figure dans la liste de visibilité d’un bon de travail sans y être affecté, vous ne recevez ses événements que si OpenWrench a activé les webhooks de visibilité pour votre entreprise. Demandez au soutien si vous en avez besoin.

​

Charge utile de la livraison

​

Événements de création et de statut

{
  "event_type": "workorder.create",
  "data": {
    "workOrderId": 9001,
    "customer": "Acme Grocery",
    "location": "Store 1204 - Denver",
    "newStatus": "PendingConfirmationByServiceProvider",
    "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/supplier/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/supplier/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 le travail dans votre système. Puis distinguez selon newStatus : PendingConfirmationByServiceProvider signifie que l’acheteur vous attend, faites donc confirm ou decline dans votre entente de service; SupplierInitiatedPendingApproval signifie que votre propre demande attend l’acheteur, ne faites donc rien tant qu’un workorder.status_update n’a pas rapporté l’issue; tout autre statut signifie que le bon de travail est déjà à vous, passez donc directement à la planification.
3. Sur workorder.status_update, récupérez le bon de travail. WorkUnsatisfactory et WorkReviewedAndCompleted vous donnent le verdict de l’acheteur; CancelledWithReason clôt le travail; PaymentMade clôt le volet financier.
4. Exécutez un sondage périodique sur assignedAt ou statusChangedAt comme filet de sécurité pour tout ce que le chemin des webhooks aurait manqué, y compris les travaux réaffectés à un autre fournisseur.