Webhooks og API-nøgler

Webhooks sender hændelser til dit system. API-nøgler lader dit system læse og skrive data.

Hvor: Settings › Developer › Webhooks og Settings › Developer › API keys. At oprette, ændre og slette kræver rollen owner eller admin.

#Webhooks

#Tilføj et endpoint

1. Åbn Settings › Developer › Webhooks.
2. Tryk New endpoint.
3. Udfyld Endpoint URL (https only) og, hvis du vil, Description (optional).
4. Tryk Create endpoint.
5. Vælg hændelser under Subscribed events på endpointets kort. Intet valg betyder alle hændelser.
6. Tryk Show ved Signing secret og kopiér hemmeligheden til din modtager.

BunStack sender nu de valgte hændelser til adressen.

• Pause stopper endpointet, og Resume starter det igen.
• Rotate secret skifter hemmeligheden. Alt, der sendes efter skiftet, signeres med den nye hemmelighed, også genforsøg. Opdatér din modtager først.

Advarsel: Under en pause sættes intet i kø til endpointet. Hændelser under pausen sendes aldrig, heller ikke når du trykker Resume. En levering, der allerede lå i køen, markeres som failed.

En levering, der mislykkedes på grund af pausen, tæller ikke mod endpointets helbred.

#Hvad BunStack sender

Hver levering er en POST med en JSON-krop og disse headers:

Kroppen er hændelsens payload plus nøglen delivery_id, med samme værdi som headeren. Deduplikér på delivery_id i kroppen. Kroppen er signeret. Headeren er ikke signeret.

#Payload

Hver krop har de samme fem nøgler:

Nøglerne i data pr. hændelse:

#Hvornår ordrehændelserne sendes

• order.paid sendes, når ordren er klar. For de fleste ordrer er det, når ordren oprettes.
• En ordre, som Kustoms svindelkontrol holder tilbage, får først order.paid, når Kustom har godkendt den.
• En ordre, som Kustom har afvist eller annulleret, får aldrig order.paid.
• order.cancelled sendes én gang, når ordren eller dens reservation annulleres. Det sker, når status eller payment_status bliver cancelled.
• En annullering, der bogfører en refusion, sender også order.refunded.
• Et endpoint uden valg får alle hændelser, også order.cancelled. Et endpoint med valg får først order.cancelled, når du vælger den.
• En annullering i Kustoms portal af en ordre, som Kustom allerede har godkendt, ser BunStack ikke. Ingen hændelse sendes.

Kontrakten blev ændret 12. september 2026 (2026-09-12). Før det blev order.paid sendt, når ordren blev oprettet, også for en tilbageholdt ordre, og order.cancelled fandtes ikke.

#Kontrollér signaturen

Signaturen er HMAC-SHA256 over den rå krop. Nøglen er hemmelighedens tegn. Brug hemmeligheden præcis, som den vises, som en ASCII-streng. Hex-afkod den ikke.

1. Læs kroppens rå bytes, før du fortolker JSON.
2. Beregn 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.

Kun kroppen er signeret. Headers er ikke signeret.

#Dubletter

Leveringen sker mindst én gang (at-least-once). Samme hændelse kan leveres flere gange. Genforsøg kan gentage en levering, der allerede er nået frem.

• delivery_id er den samme ved hvert forsøg af en hændelse. To forskellige hændelser deler aldrig id.
• Gem de id'er, du har behandlet. Spring et id over, som du har set før.
• Deduplikér ikke på indholdet. To ægte ordrer kan se ens ud, og samme ordre sendt to gange har samme krop.
• x-bunstack-attempt er til dine logs. Forsøg 2 eller højere betyder, at forrige forsøg ikke fik 2xx.

Svar 2xx, når du har gemt hændelsen. Gør arbejdet bagefter. Et svar, der ikke er 2xx, eller som tager mere end 8 sekunder, tæller som et mislykket forsøg.

#Genforsøg

Det sidste forsøg kommer 81 minutter efter det første. Efter det sidste forsøg markeres leveringen som failed. Den gentages ikke, og den bliver liggende i leveringslisten.

#Se en levering

Vælg et endpoint og åbn en levering. Du ser status, svarkoden, antal forsøg, leveringens id og kroppen præcis, som den blev sendt og signeret. Brug den krop, når du tester din signaturkontrol.

#API-nøgler

Under Settings › Developer › API keys opretter du nøgler med præfikset bunstack_. Nøglen vises én gang og gemmes hashet. En nøgle har scopes (read:products, read:orders, read:customers, read:reviews, write:products, write:orders, write:reviews). Du kan tilbagekalde den når som helst med Revoke. Adressen, kaldkropperne og fejlkoderne står på referencesiden under View docs.

#Opret en nøgle

1. Åbn Settings › Developer › API keys.
2. Tryk New key.
3. Udfyld Name og vælg Scopes.
4. Vælg en dato under Expires (optional), hvis nøglen skal holde op med at virke.
5. Tryk Create key.
6. Kopiér nøglen. Den vises ikke igen.

En nøgle med udløbsdato virker til slutningen af den dag, svensk tid. Skrivninger, der laves med en nøgle, logges i Activity log under nøglens navn. Læsninger logges ikke.

#Operationer

Hvert kald er en POST med Authorization: Bearer bunstack_… og en JSON-krop med op.

create_product og update_product tager short_description, teksten ved prisen på produktsiden, som ren tekst. Den må højst være 600 tegn. En længere tekst svarer 400 med invalid_value og field: "short_description". list_products sender den med.

En liste giver højst 500 rækker pr. side. Er siden fuld, indeholder svaret next_before. Send værdien som before for næste side.

#Ordrestatus via API'et

• update_order_status svarer 409 for status cancelled og refunded, både til og fra, for alle ordrer. Annullér og refundér i admin.
• Status fulfilled svarer 409 for en ordre med hold (Needs attention).
• Status fulfilled svarer 409 for en Kustom-ordre, hvor betalingen er reserveret, men ikke trukket.
• ProSmart-markeringerne prosmart_partial, prosmart_refund og prosmart_customer_missing regnes ikke som hold.
• En ordre, der hentes i butikken, svarer 409 store_pickup. Registrér udleveringen med Picked up i admin. Det trækker betalingen og markerer ordren som hentet.

#Kaldegrænser

Når en grænse er nået, svarer API'et 429 med { "error": "rate_limited", "retry_after": 60 } og headeren Retry-After: 60. Vent minuttet ud, før du prøver igen.