Webhooks och API-nycklar

Webhooks skickar händelser till ditt system. API-nycklar låter ditt system läsa och skriva data.

Var: Settings › Developer › Webhooks och Settings › Developer › API keys. Att skapa, ändra och ta bort kräver rollen owner eller admin.

#Webhooks

#Lägg upp en endpoint

1. Öppna Settings › Developer › Webhooks.
2. Tryck New endpoint.
3. Fyll i Endpoint URL (https only) och, om du vill, Description (optional).
4. Tryck Create endpoint.
5. Välj händelser under Subscribed events på endpointens kort. Inget val betyder alla händelser.
6. Tryck Show vid Signing secret och kopiera hemligheten till din mottagare.

BunStack skickar nu de valda händelserna till adressen.

• Pause stoppar endpointen och Resume startar den igen.
• Rotate secret byter hemligheten. BunStack signerar allt som skickas efter bytet med den nya hemligheten, även omförsök. Uppdatera din mottagare först.

Varning: Under en paus köas inget för endpointen. Händelser under pausen skickas aldrig, inte heller när du trycker Resume. En leverans som redan låg i kön markeras som failed.

En leverans som misslyckades på grund av pausen räknas inte mot endpointens hälsa.

#Vad BunStack skickar

Varje leverans är en POST med en JSON-kropp och dessa headers:

Kroppen är händelsens payload plus nyckeln delivery_id, med samma värde som headern. Deduplicera på delivery_id i kroppen. Kroppen är signerad. Headern är det inte.

#Payload

Varje kropp har samma fem nycklar:

Nycklarna i data per händelse:

#När orderhändelserna skickas

• order.paid skickas när ordern är klar. För de flesta ordrar är det när ordern skapas.
• En order som är spärrad i Kustoms bedrägerikontroll får order.paid först när Kustom godkänt den.
• En order som Kustom avvisat eller avbrutit får aldrig order.paid.
• order.cancelled skickas en gång när ordern eller dess reservation avbryts. Det sker när status eller payment_status blir cancelled.
• Ett avbrott som bokar en återbetalning skickar också order.refunded.
• En endpoint utan val får alla händelser, även order.cancelled. En endpoint med val får order.cancelled först när du väljer den.
• Avbryter du en order i Kustoms portal efter att Kustom godkänt den ser BunStack inte avbrottet. Ingen händelse skickas.

Kontraktet ändrades 12 september 2026 (2026-09-12). Före det skickades order.paid när ordern skapades, även för en hållen order, och order.cancelled fanns inte.

#Kontrollera signaturen

Signaturen är HMAC-SHA256 över den råa kroppen. Nyckeln är hemligheten exakt som den visas, som en ASCII-sträng. Hex-avkoda den inte.

1. Läs kroppens råa bytes innan du tolkar JSON.
2. Räkna ut signaturen. I Node:

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

3. Jämför expected med x-bunstack-signature med en jämförelse i konstant tid.

Bara kroppen är signerad. Headers är det inte.

#Dubbletter

Leveransen sker minst en gång (at-least-once). Samma händelse kan levereras flera gånger. Omförsök kan upprepa en leverans som redan kommit fram.

• delivery_id är samma vid varje försök av en händelse. Två olika händelser delar aldrig id.
• Spara de id du har behandlat. Hoppa över ett id du har sett förut.
• Deduplicera inte på innehållet. Två äkta ordrar kan se likadana ut, och samma order skickad två gånger har samma kropp.
• x-bunstack-attempt är till för dina loggar. Försök 2 eller högre betyder att förra försöket inte fick 2xx.

Svara 2xx när du har sparat händelsen. Gör arbetet efteråt. Ett svar som inte är 2xx, eller som tar mer än 8 sekunder, räknas som ett misslyckat försök.

#Omförsök

Det sista försöket kommer 81 minuter efter det första. Efter det sista försöket markeras leveransen som failed. Den görs inte om, och den ligger kvar i leveranslistan.

#Granska en leverans

Välj en endpoint och öppna en leverans. Du ser status, svarskoden, antal försök, leveransens id och kroppen exakt som den skickades och signerades. Använd den kroppen när du testar din signaturkontroll.

#API-nycklar

Under Settings › Developer › API keys skapar du nycklar med prefixet bunstack_. Nyckeln visas en gång och lagras hashad. En nyckel har scopes (read:products, read:orders, read:customers, read:reviews, write:products, write:orders, write:reviews). Du kan återkalla den när som helst med Revoke. Adressen, anropskropparna och felkoderna står på referenssidan under View docs.

#Skapa en nyckel

1. Öppna Settings › Developer › API keys.
2. Tryck New key.
3. Fyll i Name och välj Scopes.
4. Välj ett datum under Expires (optional) om nyckeln ska sluta gälla.
5. Tryck Create key.
6. Kopiera nyckeln. Den visas inte igen.

En nyckel med utgångsdatum fungerar till slutet av den dagen, svensk tid. Skrivningar som görs med en nyckel loggas i Activity log under nyckelns namn. Läsningar loggas inte.

#Operationer

Varje anrop är en POST med Authorization: Bearer bunstack_… och en JSON-kropp med op.

create_product och update_product tar short_description, texten vid priset på produktsidan, som ren text. Den får vara högst 600 tecken. En längre text svarar 400 med invalid_value och field: "short_description". list_products skickar den med.

En lista ger högst 500 rader per sida. Är sidan full innehåller svaret next_before. Skicka värdet som before för nästa sida.

#Orderstatus via API:t

• update_order_status svarar 409 vid byte till eller från status cancelled och refunded, för alla ordrar. Avbryt och återbetala i admin.
• Status fulfilled svarar 409 för en order med hold (Needs attention).
• Status fulfilled svarar 409 för en Kustom-order vars betalning är reserverad men inte dragen.
• ProSmart-flaggorna prosmart_partial, prosmart_refund och prosmart_customer_missing räknas inte som hold.
• En order som hämtas i butik svarar 409 store_pickup. Registrera utlämningen med Picked up i admin. Det drar betalningen och markerar ordern hämtad.

#Anropsgränser

När en gräns är nådd svarar API:t 429 med { "error": "rate_limited", "retry_after": 60 } och headern Retry-After: 60. Vänta ut minuten innan du försöker igen.