Webhookit ja API-avaimet

Webhookit lähettävät tapahtumia järjestelmääsi. API-avaimilla järjestelmäsi lukee ja kirjoittaa dataa.

Missä: Settings › Developer › Webhooks ja Settings › Developer › API keys. Luominen, muuttaminen ja poistaminen vaativat roolin owner tai admin.

#Webhookit

#Lisää endpoint

1. Avaa Settings › Developer › Webhooks.
2. Paina New endpoint.
3. Täytä Endpoint URL (https only) ja halutessasi Description (optional).
4. Paina Create endpoint.
5. Valitse tapahtumat endpointin kortilta kohdasta Subscribed events. Jos et valitse mitään, saat kaikki tapahtumat.
6. Paina Show kohdan Signing secret vieressä ja kopioi salaisuus vastaanottimeesi.

BunStack lähettää nyt valitut tapahtumat osoitteeseen.

• Pause pysäyttää endpointin, ja Resume käynnistää sen uudelleen.
• Rotate secret vaihtaa salaisuuden. Kaikki vaihdon jälkeen lähetetty allekirjoitetaan uudella salaisuudella, myös uudelleenyritykset. Päivitä vastaanottimesi ensin.

Varoitus: Tauon aikana endpointille ei jonoteta mitään. Tauon aikaisia tapahtumia ei lähetetä koskaan, ei edes kun painat Resume. Jonossa jo ollut toimitus merkitään tilaan failed.

Tauon vuoksi epäonnistunut toimitus ei vaikuta endpointin kuntoon.

#Mitä BunStack lähettää

Jokainen toimitus on POST, jossa on JSON-runko ja nämä otsakkeet:

Runko on tapahtuman payload ja lisäksi avain delivery_id, jonka arvo on sama kuin otsakkeessa. Poista kaksoiskappaleet rungon delivery_id:n perusteella. Runko on allekirjoitettu. Otsake ei ole.

#Payload

Jokaisessa rungossa on samat viisi avainta:

Avaimet kentässä data tapahtumittain:

#Milloin tilaustapahtumat lähetetään

• order.paid lähetetään, kun tilaus on valmis. Useimmilla tilauksilla se tapahtuu tilauksen luonnin yhteydessä.
• Tilaus, jonka Kustomin petostarkistus pidättää, saa order.paid-tapahtuman vasta, kun Kustom on hyväksynyt sen.
• Tilaus, jonka Kustom on hylännyt tai perunut, ei koskaan saa order.paid-tapahtumaa.
• order.cancelled lähetetään kerran, kun tilaus tai sen varaus perutaan, eli kun status tai payment_status muuttuu arvoon cancelled.
• Peruutus, joka kirjaa hyvityksen, lähettää myös order.refunded-tapahtuman.
• Endpoint ilman valintaa saa kaikki tapahtumat, myös order.cancelled. Endpoint, jolla on valinta, saa order.cancelled-tapahtuman vasta kun valitset sen.
• BunStack ei näe Kustomin portaalissa tehtyä peruutusta tilaukselle, jonka Kustom on jo hyväksynyt. Tapahtumaa ei lähetetä.

Sopimus muuttui 12.9.2026 (2026-09-12). Sitä ennen order.paid lähetettiin tilauksen luonnin yhteydessä myös pidätetylle tilaukselle, eikä order.cancelled-tapahtumaa ollut.

#Tarkista allekirjoitus

Allekirjoitus on HMAC-SHA256 raa'asta rungosta. Avain on salaisuuden merkit. Käytä salaisuutta täsmälleen sellaisena kuin se näytetään, ASCII-merkkijonona. Älä pura sitä heksasta.

1. Lue rungon raa'at tavut ennen JSONin jäsentämistä.
2. Laske allekirjoitus. Nodessa:

const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

3. Vertaa expected-arvoa otsakkeeseen x-bunstack-signature vakioaikaisella vertailulla.

Vain runko on allekirjoitettu. Otsakkeet eivät ole.

#Kaksoiskappaleet

Toimitus tapahtuu vähintään kerran (at-least-once). Sama tapahtuma voidaan toimittaa useita kertoja. Uudelleenyritykset voivat toistaa jo perille menneen toimituksen.

• delivery_id on sama tapahtuman jokaisella yrityksellä. Kaksi eri tapahtumaa ei koskaan jaa tunnusta.
• Tallenna käsittelemäsi tunnukset. Ohita tunnus, jonka olet nähnyt aiemmin.
• Älä poista kaksoiskappaleita sisällön perusteella. Kaksi aitoa tilausta voi näyttää samalta, ja kahdesti lähetetyllä tilauksella on sama runko.
• x-bunstack-attempt on lokejasi varten. Yritys 2 tai suurempi tarkoittaa, ettei edellinen yritys saanut 2xx-vastausta.

Vastaa 2xx, kun olet tallentanut tapahtuman. Tee varsinainen työ sen jälkeen. Vastaus, joka ei ole 2xx tai joka kestää yli 8 sekuntia, lasketaan epäonnistuneeksi yritykseksi.

#Uudelleenyritykset

Viimeinen yritys tulee 81 minuuttia ensimmäisen jälkeen. Viimeisen yrityksen jälkeen toimitus merkitään tilaan failed. Sitä ei yritetä uudelleen, ja se säilyy toimituslistassa.

#Tarkastele toimitusta

Valitse endpoint ja avaa toimitus. Näet tilan, vastauskoodin, yritysten määrän, toimituksen tunnuksen ja rungon täsmälleen sellaisena kuin se lähetettiin ja allekirjoitettiin. Käytä sitä runkoa, kun testaat allekirjoituksen tarkistusta.

#API-avaimet

Kohdassa Settings › Developer › API keys luot avaimia, joiden etuliite on bunstack_. Avain näytetään kerran ja tallennetaan tiivisteenä. Avaimella on scopet (read:products, read:orders, read:customers, read:reviews, write:products, write:orders, write:reviews). Voit perua sen milloin tahansa painikkeella Revoke. Osoite, kutsujen rungot ja virhekoodit ovat viitesivulla kohdassa View docs.

#Luo avain

1. Avaa Settings › Developer › API keys.
2. Paina New key.
3. Täytä Name ja valitse Scopes.
4. Valitse päivä kohdassa Expires (optional), jos avaimen on lakattava toimimasta.
5. Paina Create key.
6. Kopioi avain. Sitä ei näytetä uudelleen.

Avain, jolla on viimeinen voimassaolopäivä, toimii sen päivän loppuun Ruotsin aikaa. Avaimella tehdyt kirjoitukset kirjataan kohtaan Activity log avaimen nimellä. Lukemisia ei kirjata.

#Operaatiot

Jokainen kutsu on POST, jossa on Authorization: Bearer bunstack_… ja JSON-runko, jossa on op.

create_product ja update_product ottavat kentän short_description, tuotesivun hinnan vieressä näkyvän tekstin, pelkkänä tekstinä. Se saa olla enintään 600 merkkiä. Pidempi teksti saa vastauksen 400, jossa on invalid_value ja field: "short_description". list_products palauttaa sen.

Lista antaa enintään 500 riviä sivua kohti. Kun sivu on täynnä, vastauksessa on next_before. Lähetä arvo kenttänä before seuraavaa sivua varten.

#Tilauksen tila API:n kautta

• update_order_status vastaa 409 tiloille cancelled ja refunded, sekä niihin että niistä, kaikille tilauksille. Peru ja hyvitä adminissa.
• Tila fulfilled vastaa 409 tilaukselle, jolla on pidätys (Needs attention).
• Tila fulfilled vastaa 409 Kustom-tilaukselle, jonka maksu on varattu mutta veloittamatta.
• ProSmart-merkinnät prosmart_partial, prosmart_refund ja prosmart_customer_missing eivät ole pidätyksiä.
• Myymälästä noudettava tilaus vastaa 409 store_pickup. Kirjaa luovutus adminissa painikkeella Picked up. Se veloittaa maksun ja merkitsee tilauksen noudetuksi.

#Kutsurajat

Kun raja on täynnä, API vastaa 429 rungolla { "error": "rate_limited", "retry_after": 60 } ja otsakkeella Retry-After: 60. Odota minuutti ennen kuin yrität uudelleen.