Webhookok

A webhookok lehetővé teszik, hogy a Cost+ valós időben értesítse az Ön szerverét, amikor egy rendelés állapota megváltozik. Az API lekérdezése helyett Ön megad egy URL-t, és a Cost+ HTTP POST kérést küld rá, amikor frissítés történik.

Hogyan működnek a webhookok

Megad egy webhook_url-t a rendelés létrehozásakor, vagy beállít egy alapértelmezett webhook URL-t a projekt szintjén.
Amikor a rendelés állapota megváltozik (pl. new-ról completed-re), a Cost+ POST kérést küld az Ön webhook URL-jére.
Az Ön szervere fogadja a webhookot, majd meghívja a Cost+ API-t a teljes rendelés részleteinek lekéréséhez.
Frissíti a rendszerét az ellenőrzött rendelési állapot alapján.

Soha ne bízzon kizárólag a webhook adatcsomagban egy rendelés teljesítéséhez. Mindig ellenőrizze a rendelés állapotát egy GET /v1/orders/{id}/ kérés végrehajtásával a webhook fogadása után. A webhook egy értesítési mechanizmus, nem az igazság forrása.

Webhook adatcsomag

A webhook törzse egy JSON objektum, amely tartalmazza az eseménytípust és a rendelés azonosítóját:

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

Mező	Leírás
`event`	Az esemény típusa. Jelenleg `status_changed` a rendelés frissítésekhez.
`order_id`	Annak a rendelésnek az egyedi azonosítója, amelynek az állapota megváltozott.
`project_id`	A projekt, amelyhez a rendelés tartozik.

A webhook URL beállítása

A webhook URL-t kétféleképpen állíthatja be:

Rendelésenként

Adja meg a webhook_url mezőt a rendelés létrehozásakor:

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

Projekt alapértelmezett

Állítson be alapértelmezett webhook URL-t a Cost+ irányítópultján a projekt beállításokban. Ezt az URL-t használja az összes olyan rendelés, amely nem ad meg saját webhook_url-t.

Még ha van is projektszintű alapértelmezés, felülírhatja rendelésenként a webhook_url mező megadásával a rendelés létrehozási kérésben.

Újrapróbálkozási logika

Ha az Ön szervere nem válaszol 2xx állapotkóddal, a Cost+ újrapróbálja a webhook kézbesítést:

Maximális újrapróbálkozások: 10 kísérlet
Újrapróbálkozási időköz: 2 perc minden kísérlet között
Első kísérlet időtúllépése: 4 másodperc
További kísérletek időtúllépése: 10 másodperc

Ha mind a 10 újrapróbálkozási kísérlet sikertelen, a webhook sikertelennek lesz jelölve. A rendelés állapotát továbbra is bármikor lekérdezheti az API lekérdezésével.

Győződjön meg róla, hogy a webhook végpontja gyorsan válaszol (az első kísérlet esetén 4 másodpercen belül). A hosszan futó feldolgozást aszinkron módon végezze el, miután visszaadta a 200 OK választ.

Bevált gyakorlatok

Mindig ellenőrizze az API-n keresztül. A webhook fogadásakor hívja meg a GET /v1/orders/\{order_id\}/ végpontot az aktuális állapot megerősítéséhez, mielőtt bármilyen műveletet végezne, például áruszállítást vagy hozzáférés biztosítását.
Válaszoljon 200-zal gyorsan. Nyugtázza a webhookot 200 válasszal azonnal, és dolgozza fel a rendelést aszinkron módon az időtúllépések elkerülése érdekében.
Kezelje a duplikátumokat. A webhook végpontja többször is megkaphatja ugyanazt az eseményt. Győződjön meg róla, hogy a feldolgozási logikája idempotens.
Használjon HTTPS-t. Mindig HTTPS URL-t használjon a webhook végpontjához az adatcsomag biztonságos átvitelének biztosítása érdekében.
Naplózza a webhook adatcsomagokat. Tárolja a bejövő webhook adatokat hibakeresési és audit célokra.

Kapcsolódó végpontok

Rendelés létrehozása — a webhook_url beállítása rendelésenként
Rendelés frissítése — a webhook URL frissítése egy meglévő rendelésen
Webhook eseménysémák — adatcsomag formátum az OrderStatusChangedEvent és TransactionStatusChangedEvent eseményekhez

On this page