Webhooks i Shoporama

Webhooks gir deg muligheten til å få Shoporama til automatisk å sende en melding til en ekstern tjeneste når det skjer noe i nettbutikken din. For eksempel når en ny ordre opprettes, når et produkt oppdateres eller når en ny kunde opprettes. Her går vi gjennom hva webhooks er, hvilke hendelser du kan overvåke, og hvordan du oppretter dem.

Hva er webhooks?

En webhook er et automatisk varsel som Shoporama sender til en URL du angir, når en bestemt hendelse inntreffer. Tenk på det som et «omvendt API». I stedet for at du spør Shoporama «er det nye bestillinger?», forteller Shoporama deg det automatisk.

Uten webhooks: Tjenesten din spør Shoporama hvert 5. minutt: «Er det nye bestillinger?». Det er ineffektivt og medfører unødvendig belastning.

Med webhooks: Shoporama sender deg en melding når det kommer en ny ordre. Dette skjer automatisk, og du slipper å spørre om og om igjen.

Tilgjengelige webhook-hendelser

Du kan konfigurere webhooks for følgende hendelser. Merk at hendelsesnavnene bruker understreker (order_created) og ikke punktum. Det eneste unntaket er testhendelsen test.ping.

Bestillingshendelser

Produkt- og kategori-hendelser

Kunde- og nyhetsbrev-hendelser

Kassehendelser (kundens vei gjennom kassen)

Opprett en webhook

1. Gå til «Integrasjoner» i menyen til venstre
2. Klikk på Webhooks
3. Klikk på «Opprett webhook»
4. Angi URL-en som skal motta webhook-data
5. Velg hendelsene du vil overvåke (du kan velge flere)
6. Klikk på «Lagre»

Du kan også sende en testhendelse med hendelsen test.ping direkte fra loggsiden, slik at du kan sjekke at mottakeren din fungerer.

Format på webhook-payload

Når en hendelse utløses, sender Shoporama en HTTP POST-forespørsel til URL-en din 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
  }
}

Innholdet i data-feltet varierer avhengig av hendelsen. For produkt-, lager- og kategorihendelser tilsvarer dataobjektet det som REST-API-et returnerer for det aktuelle objektet. For ordre- og kassehendelser består innholdet av et mindre sett med nøkler, vanligvis order_id og basket_id, som du bruker til å hente resten via REST-API-et. Feltet «action» er utfylt for produkt-, lager- og kategorihendelser (create, update, delete eller status) og er null for de øvrige.

HTTP-headere

Hver webhook-forespørsel inneholder disse overskriftene, som du kan bruke til verifisering og ruting:

• Content-Type: application/json
• X-Webhook-Event, navnet på hendelsen, f.eks. order_created
• X-Webhook-Signature, en HMAC SHA-256-signatur i formatet sha256=... beregnet ut fra forespørselsteksten og webhookens hemmelige nøkkel

Verifiser signaturen

Hvis du vil være sikker på at forespørselen faktisk kommer fra Shoporama, må du verifisere X-Webhook-Signature-overskriften med den hemmelige nøkkelen du finner i webhooken din 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 mottakeren

Mottakertjenesten din må svare med HTTP-status 2xx (vanligvis 200) for å bekrefte mottakelsen. Andre statuskoder logges som feil, og du kan sende mislykkede leveranser på nytt fra loggsiden.

Bruk av webhooks

Typiske bruksområder for webhooks:

• Lagerhotel-integrasjon: send nye bestillinger automatisk til lagerhotellet, f.eks. ved betalt
• Slack/Teams-varsel: få beskjed om nye bestillinger i kanalen din ved «order_created»
• Lagersynkronisering: oppdater et eksternt system når lagerbeholdningen endres
• CRM-synkronisering: opprett kunden i Klaviyo, ActiveCampaign eller ditt eget CRM ved «customer_created»
• Automatisering: utløs arbeidsflyter i Zapier, Make eller lignende

Logg og gjenta

For hver webhook kan du se en logg over alle leveringer (svarkoder, varighet, nyttelast og feil). Du kan filtrere etter hendelsestype, status og dato. Mislykkede leveringer kan sendes på nytt manuelt med ett klikk. Loggene ryddes løpende automatisk.

Feilsøk mislykkede webhooks i loggen

Når en integrasjon plutselig ikke mottar dataene sine, er webhook-loggen det første stedet du bør sjekke. Loggen lagrer hvert eneste utgående anrop, både de som lyktes og de som mislyktes, sammen med det nøyaktige svaret Shoporama fikk tilbake. Du åpner den ved å gå til «Integrasjoner» og «Webhooks» i menyen til venstre og klikke på «Logg» ved siden av den webhooken du vil undersøke.

Begynn med de fire nøkkeltallene

Så snart det er registrert minst én forespørsel, vises det fire tall øverst på loggsiden, alle for de siste 30 dagene:

• Anrop (30 dager), hvor mange ganger Shoporama har forsøkt å anrope URL-en din
• Suksessrate: hvor stor andel av anropene som fikk et 2xx-svar tilbake
• Gjennomsnittlig responstid, den gjennomsnittlige responstiden i millisekunder
• Feil, antall anrop som mislyktes

Suksessrate vises også på selve webhook-listen i kolonnen «Suksessrate (30 dager)», slik at du umiddelbart kan se om noe er galt uten å måtte åpne hver enkelt webhook. Fargen er grønn fra 90 prosent og oppover, gul mellom 50 og 90 prosent, og rød under 50 prosent. En suksessrate som har falt fra 100 til 0, betyr nesten alltid at mottakeren har flyttet seg, lagt ned eller har innført strengere sikkerhetstiltak.

Filtrer ned til de mislykkede anropene

Under nøkkeltallene ligger selve loggen med én linje per leveringsforsøk og kolonnene Tid, Hendelse, Status, Varighet og Feil. Statusmerket er fargekodet, slik at du kan skumme gjennom siden:

• Grønt: Svar-koden ligger i 2xx-serien, og leveringen lyktes
• Oransje: svarkoden ligger i 400-serien, så mottakeren svarte, men avviste anropet
• Rødt: alt annet, det vil si serverfeil i 500-serien eller status 0

Sett filteret «Status» til «Feil» og klikk på «Filtrer». Da viser tabellen bare de anropene som ikke gikk gjennom. Du kan samtidig avgrense etter hendelse og tidsperiode ved hjelp av feltene «Fra» og «Til», noe som er praktisk hvis du vil se om problemet startet på et bestemt tidspunkt. Loggvisningen viser 50 linjer om gangen, og du kan bla videre nederst på siden.

Åpne «Loggdetaljer» for den enkelte anropen

Klikk på øyeikonet til høyre for linjen, så åpnes vinduet «Loggdetaljer» med hele historikken for akkurat den samtalen:

• Hendelse, Status, Varighet og Tid øverst
• Feilmelding, som kun vises hvis Shoporama ikke fikk tilkobling til serveren din i det hele tatt
• Forespørselsdata, den nøyaktige JSON-koden som ble sendt
• Forespørselshoder, hodene som fulgte med, inkludert den beregnede signaturen
• Svartekst, detsvaret serveren din sendte tilbake

Svarteksten er vanligvis det mest verdifulle feltet når statusen er en 400- eller 500-kode. De fleste systemer oppgir den egentlige årsaken i svaret, for eksempel at et felt mangler, at en nøkkel har utløpt eller at bestillingen allerede finnes. Feltet vises kun hvis serveren din faktisk sendte tilbake innhold, og svært lange svar blir forkortet.

Hvis du mistenker at forespørselen blir blokkert underveis av en brannmur eller en WAF, så be den som driver serveren om å se etter forespørsler med en User-Agent-header som starter med «Shoporama Webhook». Hvis de kan se forespørselen i serverloggen, ligger feilen hos mottakeren. Hvis ikke, blir forespørselen stoppet før den når frem.

Status 0 betyr at forespørselen aldri kom frem

Hvis det står 0 i Status-kolonnen, mottok Shoporama aldri et HTTP-svar. Derfor er det ingen svarkode å vise, og i stedet er feltet Feilmelding utfylt. De fire typiske årsakene er:

Test med «Send test» når du har rettet noe

Knappen «Send test» øverst på loggsiden sender et anrop med hendelsen «test.ping» til URL-en som webhooken peker på. Resultatet vises i loggen umiddelbart, akkurat som en ekte levering, slik at du kan åpne «Loggdetaljer» og se hva som skjedde. Bruk den hver gang du har endret noe hos deg selv, i stedet for å vente på at en ekte ordre skal komme inn.

Send en mislykket levering på nytt

Når feilen er rettet, kan du sende de leveringene på nytt som mislyktes i mellomtiden. Klikk på «Send på nytt»-ikonet, den sirkelformede pilen helt til høyre på logglinjen, så sender Shoporama de opprinnelige dataene til den samme URL-adressen igjen. Det er tre ting du bør vite:

• Resending oppretter en ny linje i loggen. Den opprinnelige linjen forblir med feilen, slik at du alltid kan se hele forløpet.
• Signatur og tidsstempel beregnes på nytt. X-Webhook-Signature stemmer altså fortsatt, men tidsstemplet i nyttelasten viser tidspunktet for resendingen, ikke for den opprinnelige hendelsen.
• Selve innholdet er et øyeblikksbilde fra det tidspunktet hendelsen skjedde. Hvis bestillingen er endret siden den gang, sender gjentakelsen den gamle versjonen. Hvis du trenger de aktuelle dataene, må du hente dem via REST-API-et i stedet.

Prøver Shoporama automatisk på nytt?

Nei. Hver hendelse gir nøyaktig ett leveringsforsøk. Hvis mottakeren ikke svarer, eller svarer med en feilkode, blir forsøket loggført, og så skjer det ikke mer. Det skjer ingen automatisk gjentakelse etter ett minutt, en time eller et døgn. Hvis du vil at leveringen skal sendes på nytt, må du selv klikke på «Send på nytt».

Shoporama venter maksimalt 10 sekunder på å få forbindelse til serveren din, og maksimalt 30 sekunder totalt på et svar. Hvis mottakeren din er treg, kan leveringen derfor regnes som mislykket, selv om systemet ditt rakk å behandle den.

Dette stiller tre krav til den som utvikler mottakeren:

1. Svar raskt. Send tilbake 200 umiddelbart, og lagre innholdet hos deg selv. Behandle det etterpå, slik at tunge oppslag eller en treg tredjepart ikke fører til at leveransen mislykkes.
2. Tåle duplikater. Både en videresending og en hendelse som utløses flere ganger, kan føre til at det samme anropet sendes to ganger. Mottakeren din må kunne gjenkjenne at ordren allerede er behandlet, i stedet for å opprette den på nytt.
3. Bygg et sikkerhetsnett. Hent det du eventuelt har gått glipp av et par ganger om dagen via REST-API-et, slik at et enkelt driftsavbrudd ikke koster deg bestillinger. Du finner eller oppretter nøkkelen i veiledningen «Finn eller opprett en API-nøkkel».

Hvor lenge lagres loggoppføringene?

Webhook-loggen lagrer hver levering i 45 dager, hvoretter posten slettes automatisk. Dette står også nederst på loggsiden. Ryddingen skjer automatisk, og du trenger ikke å gjøre noe.

I praksis betyr dette to ting. For det første kan du bare sende leveranser på nytt som er mindre enn 45 dager gamle. Hvis du først oppdager i neste kvartal at en integrasjon har vært nede, er de gamle postene borte, og da må du hente data via REST-API-et i stedet. For det andre dekker nøkkeltallene øverst på siden kun de siste 30 dagene, så en feil som opphørte for to måneder siden påvirker ikke lenger suksessraten din.

Hvis du trenger å kunne dokumentere leveranser lenger tilbake i tid, for eksempel overfor en revisor eller en samarbeidspartner, bør du lagre dem i ditt eget system når du mottar dem. Shoporamas logg er ment som et feilsøkingsverktøy, ikke som et arkiv.

Ofte stilte spørsmål

Hvor finner jeg listen over webhooks?

Gå til «Integrasjoner» i menyen til venstre i Shoporama-administrasjonen, og klikk på «Webhooks». Du kan også lese veiledningen vår for å se opprettede webhooks i nettbutikken din.

Hvor raskt kommer webhooken frem?

Webhooks settes i kø og sendes automatisk i bakgrunnen, vanligvis innen ett minutt. Ved stor belastning kan det ta et par minutter, så regn ikke med at en webhook kommer frem i samme sekund som hendelsen skjer.

Finnes det en «order_sent»-hendelse?

Nei. Det finnes ikke en egen hendelse for «sendt». Når du merker en ordre som sendt, utløses «new_status». Payloaden inneholder kun «order_id» og ikke selve statusen, så lytt etter hendelsen og hent ordren via REST-API-et for å se hva den har endret seg til.

Skal hendelser skrives med punktum eller understrek?

Underscore. Riktig: order_created. Feil: order.created. Den eneste hendelsen med punktum er test.ping, som brukes til testleveranser.

Kan jeg lytte etter flere hendelser i samme webhook?

Ja. Bare velg flere hendelser når du oppretter eller redigerer webhooken. Bruk X-Webhook-Event-headeren eller event-feltet i nyttelasten for å skille dem fra hverandre i mottakeren din.

Hva skjer hvis serveren min er nede?

Leveransen logges som mislykket. Du kan sende den på nytt manuelt fra loggsiden når serveren din er oppe igjen. Vi prøver ikke automatisk på nytt, så utform mottakeren din slik at den tåler at en levering av og til uteblir, og hent manglende bestillinger via REST-API-et som sikkerhetskopi.

Hvordan vet jeg at det faktisk er Shoporama som ringer?

Verifiser X-Webhook-Signature-headeren med den hemmelige nøkkelen til webhooken din. Den vises på webhooken din i Shoporama-admin. Sammenlign med en HMAC SHA-256 over den mottatte bodyen. Hvis de to ikke stemmer overens, må du avvise forespørselen.

Kan jeg bruke webhooks sammen med REST-API-et?

Ja, og det er ofte en god idé. Bruk webhooks til å motta varsler, og bruk REST-API-et til å hente fullstendige data eller utføre handlinger basert på hendelsen.

Hvor mange webhooks kan jeg opprette?

Det er ingen fast grense i Shoporama. Opprett så mange du trenger, men rydd opp i webhooksene som ikke lenger er i bruk, slik at du unngår unødvendig trafikk mot nedlagte URL-er.

Suksessraten for webhooken min har falt til 0. Hva skal jeg gjøre først?

Åpne «Logs» for webhooken, sett filteret «Status» til «Feil», og åpne den nyeste linjen ved å klikke på øye-ikonet. Hvis det står 0 i «Status», er det tilkoblingen som er feil, og feltet «Feilmelding» forteller hvorfor. Hvis det står 401, 403 eller 404, svarte mottakeren, men avviste forespørselen, og da ligger forklaringen vanligvis i «Response body». Når du har rettet feilen, klikker du på «Send test» for å sjekke at det fungerer, og deretter på «Send på nytt» for de leveransene som mislyktes. Hvis du ikke forstår feilmeldingen, kan du ta et skjermbilde av «Loggdetaljer» og sende det til den som har laget integrasjonen, eller skrive til support@shoporama.dk.

URL-en min fungerer fint i nettleseren, men loggen viser en SSL-feil. Hva er galt?

Shoporama validerer sertifikatet på mottakeren din og godtar verken selvsignerte sertifikater eller en ufullstendig sertifikatkjede. Nettlesere er mer tolerante, fordi de selv kan hente manglende mellomliggende sertifikater fra andre steder, og derfor kan den samme URL-adressen se helt fin ut i en nettleser. Be den som driver serveren om å sjekke at hele kjeden er til stede, og at sertifikatet ikke har gått ut på dato.

Lagerhotellet mitt mottok ikke bestillingen. Kan jeg sende den på nytt?

Ja. Finn linjen i loggen som viser tidspunktet da bestillingen ble opprettet, og klikk på ikonet for å sende den på nytt. Avtal med lagerhotellet at de kan tåle å motta den samme bestillingen to ganger, slik at du ikke risikerer dobbeltplukking. Hvis leveransen er eldre enn 45 dager, er loggoppføringen slettet, og da må bestillingen sendes videre manuelt.

Får jeg beskjed hvis en webhook slutter å fungere?

Nei, Shoporama sender ikke et varsel av seg selv. Derimot vises suksessraten for de siste 30 dagene direkte på webhook-listen, og merket blir rødt så snart under halvparten av anropene lykkes. Hvis du driver flere nettbutikker, er det lurt å gå gjennom listen en gang i uken, eller å la din egen mottaker slå alarm dersom den ikke har hørt fra en nettbutikk i løpet av et døgn.

Trenger du hjelp? Kontakt oss på support@shoporama.dk.