Webhook-uri

Webhook-urile permit Cost+ să notifice serverul dvs. în timp real ori de câte ori statusul unei comenzi se schimbă. În loc să interogați API-ul, furnizați un URL, iar Cost+ trimite o cerere HTTP POST către acesta ori de câte ori există o actualizare.

Cum funcționează webhook-urile

Specificați un webhook_url când creați o comandă sau configurați un URL webhook implicit la nivel de proiect.
Când statusul comenzii se schimbă (de ex., din new în completed), Cost+ trimite o cerere POST la URL-ul webhook.
Serverul dvs. primește webhook-ul, apoi apelează API-ul Cost+ pentru a prelua detaliile complete ale comenzii.
Actualizați sistemul dvs. pe baza statusului verificat al comenzii.

Nu aveți niciodată încredere doar în payload-ul webhook-ului pentru a onora o comandă. Verificați întotdeauna statusul comenzii făcând o cerere GET /v1/orders/{id}/ după ce primiți un webhook. Webhook-ul este un mecanism de notificare, nu o sursă de adevăr.

Payload-ul webhook-ului

Corpul webhook-ului este un obiect JSON care conține tipul evenimentului și ID-ul comenzii:

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

Câmp	Descriere
`event`	Tipul evenimentului. Momentan `status_changed` pentru actualizări de comenzi.
`order_id`	Identificatorul unic al comenzii al cărei status s-a schimbat.
`project_id`	Proiectul căruia îi aparține comanda.

Setarea URL-ului webhook

Puteți seta URL-ul webhook în două moduri:

Per comandă

Includeți câmpul webhook_url la crearea unei comenzi:

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

Implicit la nivel de proiect

Configurați un URL webhook implicit în dashboard-ul Cost+ la setările proiectului. Acest URL va fi utilizat pentru toate comenzile care nu specifică propriul webhook_url.

Chiar dacă aveți un URL implicit la nivel de proiect, îl puteți suprascrie per comandă incluzând webhook_url în cererea de creare a comenzii.

Logica de reîncercare

Dacă serverul dvs. nu răspunde cu un cod de stare 2xx, Cost+ reîncearcă livrarea webhook-ului:

Număr maxim de reîncercări: 10 tentative
Interval între reîncercări: 2 minute între fiecare tentativă
Timeout prima tentativă: 4 secunde
Timeout tentative ulterioare: 10 secunde

Dacă toate cele 10 tentative de reîncercare eșuează, webhook-ul este marcat ca eșuat. Puteți prelua statusul comenzii oricând prin interogarea API-ului.

Asigurați-vă că endpoint-ul webhook răspunde rapid (în 4 secunde pentru prima tentativă). Efectuați orice procesare de lungă durată asincron după ce returnați un răspuns 200 OK.

Bune practici

Verificați întotdeauna prin API. La primirea unui webhook, apelați GET /v1/orders/\{order_id\}/ pentru a confirma statusul curent înainte de a lua acțiuni precum expedierea mărfurilor sau acordarea accesului.
Returnați 200 rapid. Confirmați webhook-ul cu un răspuns 200 imediat și procesați comanda asincron pentru a evita timeout-urile.
Gestionați duplicatele. Endpoint-ul webhook poate primi același eveniment de mai multe ori. Asigurați-vă că logica de procesare este idempotentă.
Folosiți HTTPS. Utilizați întotdeauna un URL HTTPS pentru endpoint-ul webhook pentru a asigura transmiterea securizată a payload-ului.
Logați payload-urile webhook. Stocați datele webhook primite pentru depanare și audit.

Endpoint-uri asociate

Creare comandă — setați webhook_url per comandă
Actualizare comandă — actualizați URL-ul webhook pe o comandă existentă
Scheme de evenimente webhook — formatul payload-ului pentru OrderStatusChangedEvent și TransactionStatusChangedEvent

On this page