Webhooks i Shoporama

Med webhooks kan du ställa in Shoporama så att det automatiskt skickar ett meddelande till en extern tjänst när något händer i din webbutik. Till exempel när en ny beställning skapas, när en produkt uppdateras eller när en ny kund läggs till. Här går vi igenom vad webhooks är, vilka händelser du kan lyssna på och hur du skapar dem.

Vad är webhooks?

En webhook är en automatisk avisering som Shoporama skickar till en URL som du anger när en viss händelse inträffar. Tänk på det som ett ”omvänt API”. Istället för att du frågar Shoporama ”finns det nya beställningar?”, meddelar Shoporama dig detta automatiskt.

Utan webhooks: Din tjänst frågar Shoporama var femte minut: ”Finns det några nya beställningar?”. Det är ineffektivt och skapar onödig belastning.

Med webhooks: Shoporama skickar ett meddelande till dig när det finns en ny beställning. Det sker automatiskt, och du slipper fråga om och om igen.

Tillgängliga webhook-händelser

Du kan konfigurera webhooks för följande händelser. Observera att händelse namnen använder understreck (order_created) och inte punkt. Det enda undantaget är testhändelsen test.ping.

Orderhändelser

Produkt- och kategoriehändelser

Kund- och nyhetsbrevshändelser

Kassahändelser (kundens väg genom kassan)

Skapa en webhook

1. Gå till Integrationer i menyn till vänster
2. Klicka på Webhooks
3. Klicka på ”Skapa webhook”
4. Ange den URL som ska ta emot webhook-data
5. Välj de händelser du vill övervaka (du kan välja flera)
6. Klicka på Spara

Du kan också skicka en testhändelse med händelsen test.ping direkt från loggsidan, så att du kan kontrollera att din mottagare fungerar.

Format på webhook-payload

När en händelse utlöses skickar Shoporama en HTTP POST-förfrågan till din URL med data i JSON-format. Alla webhooks har samma struktur:

{
  "event": "order_created",
  "action": null,
  "timestamp": "2026-05-01T10:30:00+02:00",
  "webshop_id": 1234,
  "data": {
    "event": "order_created",
    "time": 1777624200,
    "basket_id": 98765,
    "order_id": 56789
  }
}

Innehållet i datafältet varierar beroende på händelsen. För produkt-, lager- och kategorihändelser motsvarar dataobjektet det som REST-API:et returnerar för det aktuella objektet. För order- och kassahändelser består innehållet av en mindre uppsättning nycklar, vanligtvis order_id och basket_id, som du använder för att hämta resten via REST-API:et. Fältet action är ifyllt vid produkt-, lager- och kategori-händelser (create, update, delete eller status) och är null vid övriga händelser.

HTTP-rubriker

Varje webhook-förfrågan innehåller följande rubriker som du kan använda för verifiering och vidarebefordran:

• Content-Type: application/json
• X-Webhook-Event, namnet på händelsen, t.ex. order_created
• X-Webhook-Signature, en HMAC SHA-256-signatur i formatet sha256=... beräknad utifrån begäranens innehåll och webhookens hemliga nyckel

Verifiera signaturen

Om du vill vara säker på att förfrågan verkligen kommer från Shoporama ska du verifiera X-Webhook-Signature-rubriken med den hemliga nyckeln som du kan se för din webhook i Shoporama-admin. Exempel i PHP:

$payload = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'])) {
    http_response_code(401);
    exit;
}

Svar från mottagaren

Din mottagande tjänst måste svara med HTTP-status 2xx (vanligtvis 200) för att bekräfta mottagandet. Andra statuskoder loggas som fel, och du kan skicka om misslyckade leveranser från loggsidan.

Användning av webhooks

Vanliga användningsområden för webhooks:

• Lagerhotellintegration: skicka nya beställningar automatiskt till lagerhotellet, t.ex. vid betald
• Slack/Teams-avisering: få meddelanden om nya beställningar i din kanal vid order_created
• Lagersynkronisering: uppdatera ett externt system när lagernivån sjunker
• CRM-synkronisering: skapa kunden i Klaviyo, ActiveCampaign eller ditt eget CRM vid customer_created
• Automatisering: utlös arbetsflöden i Zapier, Make eller liknande

Loggar och omförsändningar

För varje webhook kan du se en logg över alla leveranser (svarskoder, varaktighet, payload och fel). Du kan filtrera efter händelsetyp, status och datum. Misslyckade leveranser kan skickas om manuellt med ett klick. Loggarna rensas kontinuerligt automatiskt.

Felsök misslyckade webhooks i loggen

När en integration plötsligt inte får sina data är webhook-loggen det första stället du ska titta på. Loggen sparar varje utgående anrop, både de som lyckades och de som misslyckades, tillsammans med det exakta svaret som Shoporama fick tillbaka. Du öppnar den genom att gå till Integrationer och Webhooks i menyn till vänster och klicka på Loggar bredvid den webhook du vill undersöka.

Börja med de fyra nyckeltalen

Så snart minst ett anrop har registrerats visas fyra siffror högst upp på loggsidan, alla för de senaste 30 dagarna:

• Anrop (30 dagar), hur många gånger Shoporama har försökt anropa din URL
• Framgångsgrad, hur stor andel av anropen som fick ett 2xx-svar
• Genomsnittlig svarstid, den genomsnittliga svarstiden i millisekunder
• Fel, antalet misslyckade anrop

Framgångsgraden visas även i själva webhook-listan i kolumnen Framgångsgrad (30 dagar), så att du omedelbart kan se om något är fel utan att behöva öppna varje enskild webhook. Färgen är grön från 90 procent och uppåt, gul mellan 50 och 90 procent och röd under 50 procent. En framgångsgrad som har sjunkit från 100 till 0 betyder nästan alltid att mottagaren har flyttat, stängt ner eller skärpt säkerheten.

Filtrera fram de misslyckade anropen

Under nyckeltalen finns själva loggen med en rad per leveransförsök och kolumnerna Tid, Händelse, Status, Varaktighet och Fel. Statusmarkeringen är färgkodad så att du snabbt kan överblicka sidan:

• Grönt: svarskoden ligger i 2xx-serien och leveransen lyckades
• Orange: svarskoden ligger i 400-serien, vilket innebär att mottagaren svarade men avvisade anropet
• Rött: allt annat, det vill säga serverfel i 500-serien eller status 0

Ställ in filtret Status på Fel och klicka på Filtrera. Då visar tabellen endast de anrop som inte gick igenom. Du kan samtidigt avgränsa efter händelse och tidsperiod med fälten Från och Till, vilket är praktiskt om du vill se om problemet började vid en viss tidpunkt. Loggen visar 50 rader åt gången, och du bläddrar vidare längst ner på sidan.

Öppna Loggdetaljer för det enskilda anropet

Klicka på ögonikonen till höger om raden så öppnas fönstret Loggdetaljer med hela historiken för just det samtalet:

• Händelse, Status, Varaktighet och Tid högst upp
• Felmeddelande, som endast visas om Shoporama inte kunde ansluta till din server alls
• Begäranens nyttolast, den exakta JSON-data som skickades iväg
• Begäranrubriker, de rubriker som följde med, inklusive den beräknade signaturen
• Svarets huvuddel, det som din server svarade med

Svarsinnehållet är oftast det mest värdefulla fältet när statusen är en 400- eller 500-kod. De flesta system anger den egentliga orsaken i svaret, till exempel att ett fält saknas, att en nyckel har gått ut eller att beställningen redan finns. Fältet visas endast om din server faktiskt skickade tillbaka innehåll, och mycket långa svar förkortas.

Om du misstänker att anropet blockeras på vägen av en brandvägg eller en WAF, be då den som driver servern att leta efter anrop med en User-Agent-header som börjar med Shoporama Webhook. Om de kan se anropet i serverloggen ligger felet hos mottagaren. Om de inte kan det stoppas anropet innan det når fram.

Status 0 betyder att anropet aldrig nådde fram

Om det står 0 i kolumnen Status fick Shoporama aldrig något HTTP-svar. Därför finns det ingen svarskod att visa, och istället är fältet Felmeddelande ifyllt. De fyra vanligaste orsakerna är:

Testa med ”Skicka test” när du har rättat till något

Knappen ”Skicka test” högst upp på loggsidan skickar ett anrop med händelsen test.ping till den URL som webhooken pekar på. Resultatet visas omedelbart i loggen, precis som vid en riktig leverans, så att du kan öppna ”Loggdetaljer” och se vad som hände. Använd den varje gång du har ändrat något hos dig själv, istället för att vänta på att en riktig beställning ska komma in.

Skicka om en misslyckad leverans

När felet är åtgärdat kan du skicka de leveranser igen som misslyckades under tiden. Klicka på ikonen för att skicka om, den cirkelformade pilen längst till höger på loggraden, så skickar Shoporama de ursprungliga uppgifterna till samma URL igen. Tre saker är värda att veta:

• Omsändningen skapar en ny rad i loggen. Den ursprungliga raden finns kvar med sitt fel, så att du alltid kan se hela händelseförloppet.
• Signatur och tidsstämpel beräknas på nytt. X-Webhook-Signature stämmer alltså fortfarande, men tidsstämpeln i nyttolasten visar tidpunkten för återutsändningen, inte för den ursprungliga händelsen.
• Själva innehållet är en ögonblicksbild från den tidpunkt då händelsen inträffade. Om beställningen har ändrats sedan dess skickar återutsändningen den gamla versionen. Om du behöver de aktuella uppgifterna ska du istället hämta dem via REST-API:et.

Försöker Shoporama automatiskt igen?

Nej. Varje händelse ger exakt ett leveransförsök. Om mottagaren inte svarar eller svarar med en felkod skrivs försöket in i loggen, och sedan händer inget mer. Det sker ingen automatisk omförsök efter en minut, en timme eller ett dygn. Om du vill att leveransen ska göras om måste du själv klicka på ”Skicka om”.

Shoporama väntar högst 10 sekunder på att få kontakt med din server och högst 30 sekunder totalt på ett svar. Om din mottagare är långsam kan leveransen därför räknas som misslyckad, även om ditt system hann bearbeta den.

Detta ställer tre krav på den som bygger mottagaren:

1. Svara snabbt. Skicka tillbaka 200 omedelbart och spara innehållet hos dig själv. Bearbeta det efteråt, så att tunga sökningar eller en långsam tredje part inte får leveransen att misslyckas.
2. Hantera dubbletter. Både en återutsändning och en händelse som utlöses flera gånger kan resultera i att samma anrop sker två gånger. Din mottagare måste kunna känna igen att ordern redan har behandlats, istället för att skapa den på nytt.
3. Skapa ett säkerhetsnät. Hämta ett par gånger om dygnet via REST-API:et det du eventuellt har missat, så att ett enstaka driftavbrott inte kostar dig beställningar. Du hittar eller skapar nyckeln i guiden ”Hitta eller skapa en API-nyckel”.

Hur länge sparas loggposterna?

Webhook-loggen sparar varje leverans i 45 dagar, varefter posten raderas automatiskt. Det står också längst ner på loggsidan. Rensningen sker automatiskt och du behöver inte göra något.

I praktiken innebär detta två saker. För det första kan du endast skicka om leveranser som är yngre än 45 dagar. Om du först under nästa kvartal upptäcker att en integration har varit nere är de gamla posterna borta, och då måste du hämta data via REST-API:et istället. För det andra omfattar nyckeltalen högst upp på sidan endast de senaste 30 dagarna, så ett fel som uppstod för två månader sedan påverkar inte längre din framgångsgrad.

Om du behöver kunna dokumentera leveranser som ligger längre tillbaka i tiden, till exempel gentemot en revisor eller en samarbetspartner, bör du spara dem i ditt eget system när du tar emot dem. Shoporamas logg är avsedd som ett felsökningsverktyg, inte som ett arkiv.

Vanliga frågor

Var hittar jag webhook-listan?

Gå till Integrationer i vänstermenyn i din Shoporama-admin och klicka på Webhooks. Du kan också läsa vår guide för att se skapade webhooks i din butik.

Hur snabbt skickas webhooken?

Webhooks läggs i kö och skickas automatiskt i bakgrunden, vanligtvis inom en minut. Vid hög belastning kan det ta några minuter, så räkna inte med att en webhook kommer fram samma sekund som händelsen inträffar.

Finns det en ”order_sent”-händelse?

Nej. Det finns ingen separat händelse för ”skickad”. När du markerar en order som skickad utlöses new_status. Payloaden innehåller endast order_id och inte själva statusen, så lyssna på händelsen och hämta ordern via REST-API:et för att se vad den har ändrats till.

Ska händelser skrivas med punkt eller understreck?

Understreck. Korrekt: order_created. Felaktigt: order.created. Den enda händelsen med punkt är test.ping, som används för testleveranser.

Kan jag lyssna på flera händelser i samma webhook?

Ja. Välj bara flera händelser när du skapar eller redigerar webhooken. Använd X-Webhook-Event-rubriken eller händelsefältet i nyttolasten för att skilja dem åt i din mottagare.

Vad händer om min server är nere?

Leveransen loggas som misslyckad. Du kan skicka den igen manuellt från loggsidan när din server är igång igen. Vi gör inga automatiska återförsök, så utforma din mottagare så att den tål att en leverans ibland uteblir, och hämta saknade beställningar via REST API:et som en säkerhetskopia.

Hur vet jag att det verkligen är Shoporama som ringer?

Verifiera X-Webhook-Signature-rubriken med din webhooks hemliga nyckel. Den visas på din webhook i Shoporama-admin. Jämför med en HMAC SHA-256 över den mottagna body-delen. Om de två inte stämmer överens ska du avvisa begäran.

Kan jag använda webhooks tillsammans med REST-API:et?

Ja, och det är ofta en bra idé. Använd webhooks för att få meddelanden och använd REST-API:et för att hämta fullständiga data eller utföra åtgärder baserat på händelsen.

Hur många webhooks kan jag skapa?

Det finns ingen fast gräns i Shoporama. Skapa så många du behöver, men rensa bort de webhooks som inte längre används för att undvika onödig trafik mot nedlagda URL:er.

Framgångsgraden för min webhook har sjunkit till 0. Vad ska jag göra först?

Öppna Loggar för webhooken, ställ in filtret Status på Fel och öppna den senaste raden med ögonikonen. Om det står 0 i Status är det anslutningen som är fel, och fältet Felmeddelande anger varför. Om det står 401, 403 eller 404 svarade mottagaren men avvisade anropet, och då finns förklaringen vanligtvis i ”Svartext”. När du har åtgärdat felet klickar du på Skicka test för att kontrollera att det fungerar, och därefter på Skicka om för de leveranser som misslyckades. Om du inte förstår felmeddelandena, ta en skärmdump av ”Loggdetaljer” och skicka den till den som har skapat integrationen, eller skriv till support@shoporama.dk.

Min URL fungerar bra i webbläsaren, men loggen visar ett SSL-fel. Vad är fel?

Shoporama validerar certifikatet hos din mottagare och accepterar varken självsignerade certifikat eller en ofullständig certifikatkedja. Webbläsare är mer toleranta eftersom de själva kan hämta saknade mellanliggande certifikat från andra källor, och därför kan samma URL se helt normal ut i en webbläsare. Be den som driver servern att kontrollera att hela kedjan levereras och att certifikatet inte har gått ut.

Mitt lagerhotell fick inte beställningen. Kan jag skicka den igen?

Ja. Leta reda på raden i loggen som visar när beställningen skapades och klicka på ikonen för att skicka om den. Kom överens med lagerhotellet om att de kan hantera att få samma beställning två gånger, så att du inte riskerar en dubbelplockning. Om leveransen är äldre än 45 dagar har loggposten raderats, och då måste beställningen skickas vidare manuellt.

Får jag ett meddelande om en webhook slutar fungera?

Nej, Shoporama skickar inte någon varning av sig själv. Däremot visas framgångsgraden för de senaste 30 dagarna direkt i webhook-listan, och markeringen blir röd så snart mindre än hälften av anropen lyckas. Om du driver flera butiker är det en bra vana att gå igenom listan en gång i veckan, eller att låta din egen mottagare slå larm om den inte har hört av en butik på ett dygn.

Behöver du hjälp? Kontakta oss på support@shoporama.dk.