Webhookit

Webhookit mahdollistavat sen, että Cost+ ilmoittaa palvelimellesi reaaliajassa aina, kun tilauksen tila muuttuu. Pollaamisen sijaan annat URL:n, ja Cost+ lähettää HTTP POST -pyynnön siihen aina, kun päivitys tapahtuu.

Miten webhookit toimivat

Määrität webhook_url-osoitteen tilausta luodessasi tai asetat oletuswebhook-URL:n projektitasolla.
Kun tilauksen tila muuttuu (esim. new:sta completed:ksi), Cost+ lähettää POST-pyynnön webhook-URL:iin.
Palvelimesi vastaanottaa webhookin ja kutsuu sitten Cost+ API:a hakeakseen täydelliset tilaustiedot.
Päivität järjestelmäsi vahvistetun tilauksen tilan perusteella.

Älä koskaan luota pelkästään webhook-dataan tilauksen toimittamiseksi. Vahvista aina tilauksen tila tekemällä GET /v1/orders/{id}/ -pyyntö webhookin vastaanottamisen jälkeen. Webhook on ilmoitusmekanismi, ei totuuden lähde.

Webhook-data

Webhookin runko on JSON-objekti, joka sisältää tapahtumatyypin ja tilauksen tunnisteen:

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

Kenttä	Kuvaus
`event`	Tapahtuman tyyppi. Tällä hetkellä `status_changed` tilauspäivityksille.
`order_id`	Tilauksen yksilöllinen tunniste, jonka tila muuttui.
`project_id`	Projekti, johon tilaus kuuluu.

Webhook-URL:n asettaminen

Voit asettaa webhook-URL:n kahdella tavalla:

Tilauskohtaisesti

Sisällytä webhook_url-kenttä tilausta luodessasi:

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

Projektin oletus

Määritä oletuswebhook-URL Cost+-hallintapaneelissa projektin asetusten alla. Tätä URL:ää käytetään kaikille tilauksille, jotka eivät määritä omaa webhook_url-osoitettaan.

Vaikka sinulla olisi projektitason oletus, voit ohittaa sen tilauskohtaisesti sisällyttämällä webhook_url-kentän tilauksen luontipyyntöön.

Uudelleenyrityslogiikka

Jos palvelimesi ei vastaa 2xx-tilakoodilla, Cost+ yrittää webhookin toimitusta uudelleen:

Uudelleenyrityksiä enintään: 10 kertaa
Uudelleenyritysväli: 2 minuuttia yritysten välillä
Ensimmäisen yrityksen aikakatkaisu: 4 sekuntia
Myöhempien yritysten aikakatkaisu: 10 sekuntia

Jos kaikki 10 uudelleenyritystä epäonnistuvat, webhook merkitään epäonnistuneeksi. Voit silti hakea tilauksen tilan milloin tahansa pollaamalla API:a.

Varmista, että webhook-päätepisteesi vastaa nopeasti (4 sekunnin kuluessa ensimmäisen yrityksen osalta). Suorita pitkäkestoiset prosessit asynkronisesti 200 OK -vastauksen palauttamisen jälkeen.

Parhaat käytännöt

Vahvista aina API:n kautta. Webhookin vastaanottamisen jälkeen kutsu GET /v1/orders/\{order_id\}/ vahvistaaksesi nykyisen tilan ennen toimenpiteitä, kuten tavaroiden lähettämistä tai käyttöoikeuden myöntämistä.
Palauta 200 nopeasti. Kuittaa webhook 200-vastauksella välittömästi ja käsittele tilaus asynkronisesti aikakatkaisujen välttämiseksi.
Käsittele duplikaatit. Webhook-päätepisteesi saattaa vastaanottaa saman tapahtuman useammin kuin kerran. Varmista, että käsittelylogiikkasi on idempotentti.
Käytä HTTPS:ää. Käytä aina HTTPS-URL:ää webhook-päätepisteellesi varmistaaksesi, että data siirretään turvallisesti.
Kirjaa webhook-data. Tallenna saapuva webhook-data vianmääritystä ja auditointia varten.

Liittyvät päätepisteet

Luo tilaus — aseta webhook_url tilauskohtaisesti
Päivitä tilaus — päivitä olemassa olevan tilauksen webhook-URL
Webhook-tapahtumaskeemot — datan muoto OrderStatusChangedEvent- ja TransactionStatusChangedEvent-tapahtumille

On this page