> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.useopenwrench.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks i Buyer API

> Få händelser för skapad arbetsorder, statusändring och ny anteckning skickade till din egen slutpunkt i stället för att polla OpenWrench 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](/sv/buyer-api/work-orders#sätta-ihop-det-hela) 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](mailto: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](#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](/sv/buyer-api/work-orders#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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```bash theme={null}
# 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](/sv/buyer-api/introduction#hastighetsgränser), 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:

1. Registrera en slutpunkt för `workorder.create` och `workorder.status_update` (lägg till `workorder.new_note` om du speglar konversationen).
2. 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](/sv/buyer-api/work-orders#tilldela-om-en-leverantör).
3. 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`.
4. Kör en periodisk polling på `statusChangedAt` som skyddsnät för allt som webhook-vägen kan ha missat.