Webhooks i Shoporama

Webhooks giver dig mulighed for at få Shoporama til automatisk at sende en besked til en ekstern service, når der sker noget i din shop. For eksempel når en ny ordre oprettes, når et produkt opdateres, eller når en ny kunde bliver oprettet. Her gennemgår vi, hvad webhooks er, hvilke events du kan lytte på, og hvordan du opretter dem.

Hvad er webhooks?

Et webhook er en automatisk notifikation, som Shoporama sender til en URL, du angiver, når en bestemt hændelse sker. Tænk på det som en "omvendt API". I stedet for at du spørger Shoporama "er der nye ordrer?", fortæller Shoporama dig det automatisk.

Uden webhooks: Din service spørger Shoporama hvert 5. minut: "Er der nye ordrer?". Det er ineffektivt og giver unødig belastning.

Med webhooks: Shoporama sender dig besked, når der er en ny ordre. Det sker automatisk, og du slipper for at spørge igen og igen.

Tilgængelige webhook-events

Du kan opsætte webhooks for følgende hændelser. Bemærk, at event-navnene bruger underscore (order_created) og ikke punktum. Eneste undtagelse er test-eventet test.ping.

Ordre-events

Produkt- og kategori-events

Kunde- og nyhedsbrev-events

Checkout-events (kundens vej igennem kassen)

Opret en webhook

1. Gå til Integrationer i venstremenuen
2. Klik på Webhooks
3. Klik "Opret webhook"
4. Angiv den URL, der skal modtage webhook-data
5. Vælg de events, du vil lytte på (du kan vælge flere)
6. Klik Gem

Du kan også sende et test-event med eventet test.ping direkte fra log-siden, så du kan tjekke, at din modtager virker.

Format på webhook-payload

Når et event udløses, sender Shoporama en HTTP POST-request til din URL med data i JSON-format. Alle webhooks har samme 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
  }
}

Indholdet i data-feltet varierer afhængigt af eventet. For product, stock, og category svarer dataobjektet til det, REST API'et returnerer for det pågældende objekt. For ordre- og checkout-events er indholdet et mindre sæt nøgler, typisk order_id og basket_id, som du bruger til at hente resten via REST API'et. Feltet action er udfyldt på produkt-, lager-, og kategori-events (create, update, delete, eller status) og er null på de øvrige.

HTTP-headers

Hver webhook-request indeholder disse headers, du kan bruge til verifikation og routing:

• Content-Type: application/json
• X-Webhook-Event, navnet på eventet, fx order_created
• X-Webhook-Signature, en HMAC SHA-256-signatur i formatet sha256=... beregnet ud fra request-bodyen og webhookens hemmelige nøgle

Verificér signatur

Vil du være sikker på, at requestet faktisk kommer fra Shoporama, så verificér X-Webhook-Signature-headeren med den hemmelige nøgle, du kan se på din webhook i Shoporama-admin. Eksempel 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 fra din modtager

Din modtagende service skal svare med HTTP-status 2xx (typisk 200) for at bekræfte modtagelsen. Andre statuskoder logges som fejl, og du kan gensende mislykkede leveringer fra log-siden.

Brug af webhooks

Typiske anvendelser af webhooks:

• Lagerhotel-integration: send nye ordrer automatisk til lagerhotellet, fx ved paid
• Slack/Teams-notifikation: få besked om nye ordrer i din kanal ved order_created
• Lagersync: opdatér eksternt system, når stock fyrer
• CRM-sync: opret kunden i Klaviyo, ActiveCampaign, eller eget CRM ved customer_created
• Automation: trigger workflows i Zapier, Make, eller lignende

Logs og gensend

For hver webhook kan du se en log over alle leveringer (svarkoder, varighed, payload, og fejl). Du kan filtrere på event-type, status, og dato. Mislykkede leveringer kan gensendes manuelt med ét klik. Logs ryddes løbende automatisk.

Fejlsøg mislykkede webhooks i loggen

Når en integration pludselig ikke får sine data, er webhook-loggen det første sted, du skal kigge. Loggen gemmer hvert eneste udgående kald, både dem, der lykkedes, og dem, der fejlede, sammen med det præcise svar, Shoporama fik retur. Du åbner den ved at gå til Integrationer og Webhooks i venstremenuen og klikke på Logs ud for den webhook, du vil undersøge.

Start med de fire nøgletal

Så snart der er registreret mindst ét kald, står der fire tal øverst på log-siden, alle for de seneste 30 dage:

• Kald (30 dage), hvor mange gange Shoporama har forsøgt at kalde din URL
• Success rate, hvor stor en andel af kaldene, der fik et 2xx-svar retur
• Avg. responstid, den gennemsnitlige svartid i millisekunder
• Fejl, antallet af kald, der ikke lykkedes

Success rate står også på selve webhook-listen i kolonnen Success rate (30 dage), så du kan se med det samme, om noget er galt, uden at åbne hver enkelt webhook. Mærkatet er grønt fra 90 procent og opefter, gult mellem 50 og 90 procent, og rødt under 50 procent. En success rate, der er faldet fra 100 til 0, betyder næsten altid, at modtageren er flyttet, lukket ned, eller har fået strammere sikkerhed.

Filtrér ned til de fejlede kald

Under nøgletallene ligger selve loggen med en linje pr. leveringsforsøg og kolonnerne Tid, Event, Status, Varighed, og Fejl. Status-mærkatet er farvekodet, så du kan skimme siden:

• Grønt, svarkoden ligger i 2xx-serien, og leveringen lykkedes
• Orange, svarkoden ligger i 400-serien, så din modtager svarede, men afviste kaldet
• Rødt, alt andet, altså serverfejl i 500-serien eller status 0

Sæt filteret Status til Fejl, og klik Filtrer. Så viser tabellen kun de kald, der ikke gik igennem. Du kan samtidig afgrænse på event og på en periode med felterne Fra og Til, hvilket er praktisk, hvis du vil se, om problemet startede på et bestemt tidspunkt. Loggen viser 50 linjer ad gangen, og du bladrer videre nederst på siden.

Åbn Log detaljer på det enkelte kald

Klik på øje-ikonet i højre side af linjen, så åbnes vinduet Log detaljer med hele historien om netop det kald:

• Event, Status, Varighed, og Tid øverst
• Fejlbesked, som kun vises, hvis Shoporama slet ikke fik forbindelse til din server
• Request payload, den nøjagtige JSON, der blev sendt afsted
• Request headers, de headers, der fulgte med, inklusive den beregnede signatur
• Response body, det, din server svarede tilbage

Response body er som regel det mest værdifulde felt, når status er en 400- eller 500-kode. De fleste systemer skriver den egentlige årsag i svaret, for eksempel at et felt mangler, at en nøgle er udløbet, eller at ordren allerede findes. Feltet vises kun, hvis din server rent faktisk sendte indhold retur, og meget lange svar bliver forkortet.

Har du mistanke om, at kaldet bliver blokeret undervejs af en firewall eller en WAF, så bed den, der driver serveren, om at kigge efter kald med en User-Agent-header, der starter med Shoporama Webhook. Kan de se kaldet i serverloggen, ligger fejlen hos modtageren. Kan de ikke, bliver kaldet stoppet, før det når frem.

Status 0 betyder, at kaldet aldrig nåede frem

Står der 0 i Status-kolonnen, fik Shoporama aldrig et HTTP-svar. Derfor er der ingen svarkode at vise, og i stedet er feltet Fejlbesked udfyldt. De fire typiske årsager er:

Test med Send test, når du har rettet noget

Knappen Send test øverst på log-siden sender et kald med eventet test.ping til den URL, webhooken peger på. Resultatet står i loggen med det samme, præcis som en rigtig levering, så du kan åbne Log detaljer og se, hvad der skete. Brug den, hver gang du har ændret noget hos dig selv, i stedet for at vente på, at der falder en rigtig ordre ind.

Gensend en mislykket levering

Når fejlen er rettet, kan du sende de leveringer igen, der nåede at fejle imens. Klik på gensend-ikonet, den cirkelformede pil yderst til højre på log-linjen, så sender Shoporama de oprindelige data afsted til den samme URL igen. Tre ting er værd at vide:

• Gensend laver en ny linje i loggen. Den oprindelige linje bliver stående med sin fejl, så du altid kan se hele forløbet.
• Signatur og tidsstempel beregnes på ny. X-Webhook-Signature passer altså stadig, men timestamp i payloaden viser tidspunktet for gensendelsen, ikke for den oprindelige hændelse.
• Selve indholdet er et øjebliksbillede fra det tidspunkt, hvor hændelsen skete. Er ordren ændret siden, sender gensendelsen den gamle version. Skal du bruge de aktuelle data, så hent dem via REST API'et i stedet.

Prøver Shoporama automatisk igen?

Nej. Hver hændelse giver præcis ét leveringsforsøg. Svarer din modtager ikke, eller svarer den med en fejlkode, bliver forsøget skrevet i loggen, og så sker der ikke mere. Der er ingen automatisk gentagelse efter et minut, en time, eller et døgn. Vil du have leveringen afsted igen, skal du selv klikke Gensend.

Shoporama venter højst 10 sekunder på at få forbindelse til din server, og højst 30 sekunder i alt på et svar. Er din modtager langsom, kan leveringen derfor tælle som fejlet, selvom dit system nåede at behandle den.

Det stiller tre krav til den, der bygger modtageren:

1. Svar hurtigt. Send 200 tilbage med det samme, og gem indholdet hos dig selv. Behandl det bagefter, så tunge opslag eller en langsom tredjepart ikke får leveringen til at fejle.
2. Tål dubletter. Både en gensendelse og et event, der udløses flere gange, kan give det samme kald to gange. Din modtager skal kunne genkende, at ordren allerede er behandlet, i stedet for at oprette den igen.
3. Byg et sikkerhedsnet. Hent et par gange i døgnet via REST API'et det, du eventuelt er gået glip af, så en enkelt nedetid ikke koster dig ordrer. Du finder eller opretter nøglen i guiden find eller opret en API-nøgle.

Hvor længe gemmes logposterne?

Webhook-loggen gemmer hver levering i 45 dage, hvorefter posten slettes automatisk. Det står også nederst på log-siden. Oprydningen sker automatisk, og du skal ikke foretage dig noget.

I praksis betyder det to ting. For det første kan du kun gensende leveringer, der er under 45 dage gamle. Opdager du først i næste kvartal, at en integration har været død, er de gamle poster væk, og så må du hente data via REST API'et i stedet. For det andet dækker nøgletallene øverst på siden kun de seneste 30 dage, så en fejl, der stoppede for to måneder siden, farver ikke længere din success rate.

Har du brug for at kunne dokumentere leveringer længere tilbage, for eksempel over for en revisor eller en samarbejdspartner, så gem dem i dit eget system, når du modtager dem. Shoporamas log er tænkt som et fejlsøgningsværktøj, ikke som et arkiv.

Ofte stillede spørgsmål

Hvor finder jeg webhook-listen?

Gå til Integrationer i venstremenuen i din Shoporama-admin, og klik på Webhooks. Du kan også læse vores guide til at se oprettede webhooks i din shop.

Hvor hurtigt kommer webhook'en frem?

Webhooks lægges i kø og sendes af sig selv i baggrunden, typisk inden for et minut. Ved spidsbelastning kan der gå et par minutter, så regn ikke med, at en webhook er fremme i samme sekund, hændelsen sker.

Er der et "order_sent"-event?

Nej. Der findes ikke et selvstændigt event for "sendt". Når du markerer en ordre som sendt, udløses new_status. Payloaden indeholder kun order_id og ikke selve statussen, så lyt på eventet og hent ordren via REST API'et for at se, hvad den er skiftet til.

Skal events skrives med punktum eller underscore?

Underscore. Korrekt: order_created. Forkert: order.created. Det eneste event med punktum er test.ping, som bruges til testleverancer.

Kan jeg lytte på flere events i samme webhook?

Ja. Vælg blot flere events, når du opretter eller redigerer webhooken. Brug X-Webhook-Event-headeren eller event-feltet i payloaden til at skelne dem i din modtager.

Hvad sker der, hvis min server er nede?

Leveringen logges som fejlet. Du kan gensende den manuelt fra log-siden, når din server er oppe igen. Vi forsøger ikke automatisk igen, så design din modtager til at kunne tåle, at en levering indimellem udebliver, og hent manglende ordrer via REST API'et som backup.

Hvordan ved jeg, at det faktisk er Shoporama, der ringer?

Verificér X-Webhook-Signature-headeren med din webhooks hemmelige nøgle. Den vises på din webhook i Shoporama-admin. Sammenlign med en HMAC SHA-256 over den modtagne body. Stemmer de to ikke overens, så afvis requestet.

Kan jeg bruge webhooks sammen med REST API'et?

Ja, og det er ofte en god idé. Brug webhooks til at få besked, og brug REST API'et til at hente fulde data eller udføre handlinger på baggrund af eventet.

Hvor mange webhooks kan jeg oprette?

Der er ingen hård grænse i Shoporama. Opret så mange, du har brug for, men ryd op i de webhooks, der ikke længere bruges, så du undgår unødig trafik mod nedlagte URL'er.

Success rate på min webhook er faldet til 0. Hvad gør jeg først?

Åbn Logs på webhooken, sæt filteret Status til Fejl, og åbn den nyeste linje med øje-ikonet. Står der 0 i Status, er det forbindelsen, der er galt, og feltet Fejlbesked fortæller, hvorfor. Står der 401, 403, eller 404, svarede modtageren, men afviste kaldet, og så ligger forklaringen typisk i Response body. Når du har rettet fejlen, klikker du Send test for at kontrollere, at det virker, og derefter Gensend på de leveringer, der nåede at fejle. Forstår du ikke fejlbeskeden, så tag et skærmbillede af Log detaljer og send det til den, der har lavet integrationen, eller skriv til support@shoporama.dk.

Min URL virker fint i browseren, men loggen viser en SSL-fejl. Hvad er galt?

Shoporama validerer certifikatet på din modtager, og accepterer hverken selvsignerede certifikater eller en ufuldstændig certifikatkæde. Browsere er mere tilgivende, fordi de selv kan hente manglende mellemcertifikater andre steder fra, og derfor kan den samme URL godt se helt fin ud i en browser. Bed den, der driver serveren, om at kontrollere, at hele kæden udleveres, og at certifikatet ikke er udløbet.

Mit lagerhotel fik ikke ordren. Kan jeg sende den igen?

Ja. Find linjen i loggen på det tidspunkt, hvor ordren blev oprettet, og klik på gensend-ikonet. Aftal med lagerhotellet, at de kan tåle at få den samme ordre to gange, så du ikke risikerer et dobbeltpluk. Er leveringen mere end 45 dage gammel, er logposten slettet, og så må ordren sendes videre manuelt.

Får jeg besked, hvis en webhook holder op med at virke?

Nej, Shoporama sender ikke en advarsel af sig selv. Til gengæld står success rate for de seneste 30 dage direkte på webhook-listen, og mærkatet bliver rødt, så snart under halvdelen af kaldene lykkes. Driver du flere shops, er det en god vane at kigge listen igennem en gang om ugen, eller at lade din egen modtager slå alarm, hvis den ikke har hørt fra en shop i et døgn.

Har du brug for hjælp? Kontakt os på support@shoporama.dk.