Webhooks i Buyer API

Webhooks skickar tre arbetsorderhändelser till en HTTPS-slutpunkt som du äger: en arbetsorder skapades, dess status ändrades, eller en anteckning lades till på den. Varje leverans talar om vilken arbetsorder som ändrades och vad som hände. Din integration hämtar sedan arbetsordern via API:et. Det gör webhooks till den naturliga utlösaren för en dispatch-integration: reagera på workorder.create och workorder.status_update när de inträffar, och behåll polling bara som en reserv för avstämning.

Sätta upp en slutpunkt

Slutpunkter registreras per köparföretag och täcker alla dess platser och anläggningar. Det finns ännu inget självbetjänings-API för detta: mejla support@useopenwrench.com med

HTTPS-URL:en som ska ta emot leveranserna,
vilka av de tre händelserna du vill ha (workorder.create, workorder.status_update, workorder.new_note), och
om slutpunkten är för test eller produktion.

Supporten registrerar slutpunkten på OpenWrenchs webhook-gateway och skickar tillbaka signeringshemligheten som du använder för att verifiera leveranser. Du kan registrera flera slutpunkter, till exempel en URL per händelsetyp, eller samma URL för alla tre.

Händelser

`event_type`	Utlöses när
`workorder.create`	En arbetsorder skapas i ditt företag.
`workorder.status_update`	En arbetsorders `status` byter värde.
`workorder.new_note`	En anteckning läggs till i en arbetsorders tråd mellan köpare och leverantör.

Lite mer om var och en:

workorder.create utlöses vid varje skapande, oavsett vem som gör det: din egen POST /v1/buyer/work_order/work_orders, en användare i OpenWrenchs webb- eller mobilappar, ett schema för planerat underhåll, en platsbesiktning, eller en leverantör som öppnar en arbetsorder på en av dina platser (SupplierInitiatedPendingApproval). Nyttolasten innehåller startstatusen, så du kan skilja en servicebegäran som väntar på godkännande från en arbetsorder som tilldelades direkt vid skapandet.
workorder.status_update utlöses vid varje övergång i statusmodellen, för statusar som ägs av endera sidan. Ändringar som lämnar status orörd (en prioritetsändring, ett nytt uppskattat slutdatum, en omtilldelning medan arbetsordern fortfarande väntar på bekräftelse) ger ingen händelse. När en arbetsorder flyttas från en leverantör till en annan kan du få en mellanliggande uppdatering vars newStatus är Rejected, som avslutar den tidigare tilldelningen, följd av uppdateringen för den nya statusen.
workorder.new_note utlöses för anteckningar i rottråden mellan köpare och leverantör från endera sidan, inklusive anteckningar som din egen integration postar, massuppladdningar av foton och anteckningen som bifogas en statusåtgärd. Leverantörernas interna anteckningar och underleverantörstrådar ger aldrig händelser.

Du får händelser för ändringar som din egen integration gör. Om du speglar arbetsordrar till ett annat system, håll reda på de skrivningar du gjort och hoppa över de matchande händelserna, eller behandla varje händelse som en signal att hämta om och jämföra.

Leveransens nyttolast

Varje leverans är en HTTP POST med en JSON-kropp. Kroppen har två fält: event_type och data.

Skapande- och statushändelser

{
  "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"
  }
}

Fält	Anteckningar
`workOrderId`	Arbetsorderns numeriska `id`. Använd det med `GET /v1/buyer/work_order/work_orders/{id}`.
`location`	Platsens visningsnamn.
`oldStatus`	Föregående status. Saknas på `workorder.create`.
`newStatus`	Nuvarande status, eller startstatusen på `workorder.create`.
`changedBy`	Visningsnamn för personen eller systemet som gjorde ändringen.
`changedAt`	ISO 8601-tidsstämpel med tidszonsförskjutning.

workorder.create använder samma data-form utan oldStatus.

Anteckningshändelser

{
  "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"
  }
}

Fält	Anteckningar
`workOrderId`	Arbetsorderns numeriska `id`.
`newNote`	Anteckningstexten. Tom för anteckningar som bara innehåller ett foto.
`photo`, `video`	Media-URL på anteckningen, när sådan finns.
`photos`	Finns på massuppladdningar av foton: alla foto-URL:er i satsen, i ordning.
`addedBy`	Författarens visningsnamn.
`addedAt`	ISO 8601-tidsstämpel med tidszonsförskjutning.

Nyttolasten innehåller inte resten av tråden. Läs den med GET /v1/buyer/work_order/work_order_notes/{woId} om du behöver sammanhang.

Verifiera leveranser

Varje leverans är signerad. Gatewayen beräknar en HMAC över den råa förfrågningskroppen med din slutpunkts signeringshemlighet och skickar den i ett signaturhuvud. När supporten registrerar din slutpunkt ger de dig hemligheten, huvudets namn och hash-algoritmen. Verifiera signaturen mot kroppens råa bytes innan du tolkar den, och avvisa allt som inte stämmer. Eftersom hemligheten är per slutpunkt är rotation en supportförfrågan: be om en ny hemlighet, driftsätt den, och be sedan supporten byta över slutpunkten.

Svar, omförsök och dubbletter

Bekräfta snabbt. Returnera 2xx så snart du har lagrat händelsen, och gör uppföljningsarbetet (hämta arbetsordern, uppdatera ditt system) asynkront. Ett svar som inte är 2xx eller en timeout räknas som en misslyckad leverans.
Misslyckade leveranser görs om av gatewayen enligt ett schema med ökande väntetid. Gör din hanterare idempotent så att ett omförsök efter en delvis lyckad körning inte gör skada.
Leveranser sker minst en gång. Samma händelse kan komma mer än en gång även utan något fel på din sida. Deduplicera på event_type plus workOrderId plus changedAt (eller addedAt för anteckningar).
Ordningen garanteras inte. Två händelser för samma arbetsorder kan komma i fel ordning. Härled inte tillståndet ur händelsesekvensen; hämta arbetsordern och lita på dess status.
Gamla händelser kastas, de levereras inte sent. En händelse som inte har lämnats över till gatewayen inom tre timmar från ändringen kastas. Efter ett avbrott på OpenWrenchs sida, eller om din slutpunkt var nere längre än omförsöksfönstret, stäm av genom att polla GET /v1/buyer/work_order/work_orders?statusChangedAt=... för perioden du missade.

Reagera på en händelse

Den rekommenderade hanteraren är liten: verifiera, lagra, bekräfta, hämta sedan.

# 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"

Läsningar i det externa API:et serveras från en läs-replika, så en arbetsorder som nyss skapades kan kortvarigt komma tillbaka tom. Försök hämta igen efter en sekund innan du betraktar den som saknad. Hämtningen räknas mot hastighetsgränsen, så slå ihop skurar av händelser för samma arbetsorder till en enda hämtning.

Sätta ihop det hela

En dispatch-integration driven av webhooks:

Registrera en slutpunkt för workorder.create och workorder.status_update (lägg till workorder.new_note om du speglar konversationen).
Vid workorder.create, hämta arbetsordern och skapa motsvarande post i ditt system. Om du tilldelar från din sida, gör en PATCH av supplierFacilityId enligt Arbetsordrar.
Vid workorder.status_update, hämta arbetsordern. När newStatus är WaitingForReview, kör ditt granskningsflöde och posta work_reviewed_and_completed eller work_unsatisfactory.
Kör en periodisk polling på statusChangedAt som skyddsnät för allt som webhook-vägen kan ha missat.

Kom igång

Guider

API-referens

Internal Teams API

Sätta upp en slutpunkt

Händelser

Leveransens nyttolast

Skapande- och statushändelser

Anteckningshändelser

Verifiera leveranser

Svar, omförsök och dubbletter

Reagera på en händelse

Sätta ihop det hela

​Sätta upp en slutpunkt

​Händelser

​Leveransens nyttolast

​Skapande- och statushändelser

​Anteckningshändelser

​Verifiera leveranser

​Svar, omförsök och dubbletter

​Reagera på en händelse

​Sätta ihop det hela

Sätta upp en slutpunkt

Händelser

Leveransens nyttolast

Skapande- och statushändelser

Anteckningshändelser

Verifiera leveranser

Svar, omförsök och dubbletter

Reagera på en händelse

Sätta ihop det hela