Webhooks og API-nøkler

Webhooks sender hendelser til systemet ditt. API-nøkler lar systemet ditt lese og skrive data.

Hvor: Settings › Developer › Webhooks og Settings › Developer › API keys. Å opprette, endre og slette krever rollen owner eller admin.

#Webhooks

#Legg til et endepunkt

1. Åpne Settings › Developer › Webhooks.
2. Trykk New endpoint.
3. Fyll inn Endpoint URL (https only) og, hvis du vil, Description (optional).
4. Trykk Create endpoint.
5. Velg hendelser under Subscribed events på endepunktets kort. Ingen valg betyr alle hendelser.
6. Trykk Show ved Signing secret og kopier hemmeligheten til mottakeren din.

BunStack sender nå de valgte hendelsene til adressen.

• Pause stopper endepunktet, og Resume starter det igjen.
• Rotate secret bytter hemmeligheten. Alt som sendes etter byttet, signeres med den nye hemmeligheten, også nye forsøk. Oppdater mottakeren din først.

Advarsel: Under en pause køes ingenting for endepunktet. Hendelser under pausen sendes aldri, heller ikke når du trykker Resume. En leveranse som allerede lå i køen, merkes som failed.

En leveranse som feilet på grunn av pausen, teller ikke mot endepunktets helse.

#Hva BunStack sender

Hver leveranse er en POST med en JSON-kropp og disse headerne:

Kroppen er hendelsens payload pluss nøkkelen delivery_id, med samme verdi som headeren. Dedupliser på delivery_id i kroppen. Kroppen er signert. Headeren er det ikke.

#Payload

Hver kropp har de samme fem nøklene:

Nøklene i data per hendelse:

#Når ordrehendelsene sendes

• order.paid sendes når ordren er klar. For de fleste ordrer er det når ordren opprettes.
• En ordre som Kustoms svindelkontroll holder tilbake, får order.paid først når Kustom har godkjent den.
• En ordre som Kustom har avvist eller kansellert, får aldri order.paid.
• order.cancelled sendes én gang når ordren eller reservasjonen kanselleres. Det skjer når status eller payment_status blir cancelled.
• En kansellering som bokfører en refusjon, sender også order.refunded.
• Et endepunkt uten valg får alle hendelser, også order.cancelled. Et endepunkt med valg får order.cancelled først når du velger den.
• En kansellering i Kustoms portal av en ordre som Kustom allerede har godkjent, ser ikke BunStack. Ingen hendelse sendes.

Kontrakten ble endret 12. september 2026 (2026-09-12). Før det ble order.paid sendt når ordren ble opprettet, også for en tilbakeholdt ordre, og order.cancelled fantes ikke.

#Kontroller signaturen

Signaturen er HMAC-SHA256 over den rå kroppen. Nøkkelen er hemmelighetens tegn. Bruk hemmeligheten nøyaktig slik den vises, som en ASCII-streng. Ikke hex-dekod den.

1. Les kroppens rå bytes før du tolker JSON.
2. Regn ut signaturen. I Node:

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

3. Sammenlign expected med x-bunstack-signature med en sammenligning i konstant tid.

Bare kroppen er signert. Headerne er det ikke.

#Duplikater

Leveransen skjer minst én gang (at-least-once). Samme hendelse kan leveres flere ganger. Nye forsøk kan gjenta en leveranse som allerede har kommet frem.

• delivery_id er den samme ved hvert forsøk av en hendelse. To ulike hendelser deler aldri id.
• Lagre id-ene du har behandlet. Hopp over en id du har sett før.
• Ikke dedupliser på innholdet. To ekte ordrer kan se like ut, og samme ordre sendt to ganger har samme kropp.
• x-bunstack-attempt er til loggene dine. Forsøk 2 eller høyere betyr at forrige forsøk ikke fikk 2xx.

Svar 2xx når du har lagret hendelsen. Gjør arbeidet etterpå. Et svar som ikke er 2xx, eller som tar mer enn 8 sekunder, teller som et feilet forsøk.

#Nye forsøk

Det siste forsøket kommer 81 minutter etter det første. Etter det siste forsøket merkes leveransen som failed. Den prøves ikke igjen, og den blir liggende i leveranselisten.

#Se på en leveranse

Velg et endepunkt og åpne en leveranse. Du ser status, svarkoden, antall forsøk, leveransens id og kroppen nøyaktig slik den ble sendt og signert. Bruk den kroppen når du tester signaturkontrollen din.

#API-nøkler

Under Settings › Developer › API keys oppretter du nøkler med prefikset bunstack_. Nøkkelen vises én gang og lagres hashet. En nøkkel har scopes (read:products, read:orders, read:customers, read:reviews, write:products, write:orders, write:reviews). Du kan trekke den tilbake når som helst med Revoke. Adressen, kallkroppene og feilkodene står på referansesiden under View docs.

#Opprett en nøkkel

1. Åpne Settings › Developer › API keys.
2. Trykk New key.
3. Fyll inn Name og velg Scopes.
4. Velg en dato under Expires (optional) hvis nøkkelen skal slutte å gjelde.
5. Trykk Create key.
6. Kopier nøkkelen. Den vises ikke igjen.

En nøkkel med utløpsdato virker til slutten av den dagen, svensk tid. Skrivinger som gjøres med en nøkkel, logges i Activity log under nøkkelens navn. Lesinger logges ikke.

#Operasjoner

Hvert kall er en POST med Authorization: Bearer bunstack_… og en JSON-kropp med op.

create_product og update_product tar short_description, teksten ved prisen på produktsiden, som ren tekst. Den kan være høyst 600 tegn. En lengre tekst svarer 400 med invalid_value og field: "short_description". list_products sender den med.

En liste gir høyst 500 rader per side. Er siden full, inneholder svaret next_before. Send verdien som before for neste side.

#Ordrestatus via API-et

• update_order_status svarer 409 for status cancelled og refunded, både til og fra, for alle ordrer. Kanseller og refunder i admin.
• Status fulfilled svarer 409 for en ordre med hold (Needs attention).
• Status fulfilled svarer 409 for en Kustom-ordre der betalingen er reservert, men ikke trukket.
• ProSmart-flaggene prosmart_partial, prosmart_refund og prosmart_customer_missing regnes ikke som hold.
• En ordre som hentes i butikk, svarer 409 store_pickup. Registrer utleveringen med Picked up i admin. Det trekker betalingen og merker ordren som hentet.

#Kallgrenser

Når en grense er nådd, svarer API-et 429 med { "error": "rate_limited", "retry_after": 60 } og headeren Retry-After: 60. Vent ut minuttet før du prøver igjen.