Webhooks

Webhooks gör det möjligt för Cost+ att meddela din server i realtid när en orders status ändras. Istället för att polla API:et anger du en URL och Cost+ skickar en HTTP POST-förfrågan till den varje gång en uppdatering sker.

Hur webhooks fungerar

Du anger en webhook_url när du skapar en order, eller konfigurerar en standard-webhook-URL på projektnivå.
När orderstatus ändras (t.ex. från new till completed) skickar Cost+ en POST-förfrågan till din webhook-URL.
Din server tar emot webhooken och anropar sedan Cost+ API:et för att hämta fullständiga orderdetaljer.
Du uppdaterar ditt system baserat på den verifierade orderstatusen.

Lita aldrig på webhook-payloaden ensam för att uppfylla en order. Verifiera alltid orderstatusen genom att göra en GET /v1/orders/{id}/-förfrågan efter att du mottagit en webhook. Webhooken är en notifieringsmekanism, inte en sanningskälla.

Webhook-payload

Webhook-kroppen är ett JSON-objekt som innehåller händelsetyp och order-ID:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}

Fält	Beskrivning
`event`	Typen av händelse. För närvarande `status_changed` för orderuppdateringar.
`order_id`	Den unika identifieraren för ordern vars status ändrades.
`project_id`	Projektet som ordern tillhör.

Ange webhook-URL

Du kan ange webhook-URL:en på två sätt:

Per order

Inkludera fältet webhook_url när du skapar en order:

{
  "currency": "EUR",
  "amount": 1295,
  "webhook_url": "https://www.example.com/webhook"
}

Projektstandard

Konfigurera en standard-webhook-URL i din Cost+-instrumentpanel under projektinställningar. Denna URL används för alla ordrar som inte anger sin egen webhook_url.

Även om du har en projektstandard kan du åsidosätta den per order genom att inkludera webhook_url i orderförfrågan.

Omförsökslogik

Om din server inte svarar med en 2xx-statuskod försöker Cost+ leverera webhooken igen:

Maximalt antal omförsök: 10 försök
Omförsöksintervall: 2 minuter mellan varje försök
Timeout för första försöket: 4 sekunder
Timeout för efterföljande försök: 10 sekunder

Om alla 10 omförsök misslyckas markeras webhooken som misslyckad. Du kan fortfarande hämta orderstatus när som helst genom att polla API:et.

Se till att din webhook-endpoint svarar snabbt (inom 4 sekunder för det första försöket). Utför eventuell tidskrävande bearbetning asynkront efter att ha returnerat ett 200 OK-svar.

Bästa praxis

Verifiera alltid via API:et. Vid mottagande av en webhook, anropa GET /v1/orders/\{order_id\}/ för att bekräfta aktuell status innan du vidtar åtgärder som att skicka varor eller ge åtkomst.
Returnera 200 snabbt. Bekräfta webhooken med ett 200-svar omedelbart och bearbeta ordern asynkront för att undvika timeout.
Hantera dubbletter. Din webhook-endpoint kan ta emot samma händelse mer än en gång. Se till att din bearbetningslogik är idempotent.
Använd HTTPS. Använd alltid en HTTPS-URL för din webhook-endpoint för att säkerställa att payloaden överförs säkert.
Logga webhook-payloads. Spara inkommande webhook-data för felsökning och revision.

Relaterade endpoints

Skapa order — ange webhook_url per order
Uppdatera order — uppdatera webhook-URL:en på en befintlig order
Webhook-händelsescheman — payloadformat för OrderStatusChangedEvent och TransactionStatusChangedEvent

On this page