Webhooks

I denne artikel:


Introduktion

   Du kan bruge webhooks til at modtage notifikationer om særlige begivenheder i shoppen. Webhooks lader din applikation reagere på begivenheder umiddelbart efter de sker i shoppen, i stedet for periodisk at skulle hente data via API'et. For eksempel kan du bruge webhooks til at udløse en handling i din applikation når en kunde opretter en ordre, eller når en ordre afsendes. Ved at bruge webhooks kan du lave færre API kald alt i alt, hvilket gør at din applikation er mere effektiv og opdateres hurtigt.

 

Webhooks indhold

Efter du har oprettet et webhook, vil du med hvert event som indeholder det emne du har specificeret, modtage en notifikation herom. Denne notifikation indeholder et JSON indkodet payload med relevante data og HTTP headers, som indeholder emnet for notifikationen.

I HTTP anmodningens body ligger et JSON indkodet payload. I øjeblikket suppleres udelukkende ID'et af det påvirkede element. For eksempel vil en orders/created notifikation for et ordre ID some-order-id indeholde følgende i sit HTTP request body:

{"id":"some-order-id"}

Ud over informationerne i body, suppleres med yderligere informationer via følgende headers (i forlængelse af eksemplet ovenfor):

• X-Hmac-Sha256: yRpDZI7InNvbWUtb5JkZXItaWQifV1dE5VjyVtZZ7m9moybIzqd7bRQnclM0jLcG4SDJgfQ
• X-Webhook-Topic: orders/created
• X-Shop-Domain: https://...(URI)

Du behøver ikke nødvendigvis bruge denne information til noget, men den kan benyttes til at udbygge funktionaliteten og sikkerheden i din applikation. For eksempel X-Hmac-Sha256 benyttes til at verificere webhooks og X-Shop-Domain benyttes til at identificere hvilken shop den udløste event er associeret med.

 

Understøttede emner

Følgende er en komplet liste over understøttede emner, efter kategori.

Kategori Emner
Ordrer orders/cancelledorders/createdorders/fulfilledorders/invoiceorders/partially-fulfilledorders/updated

 

Konfiguration af Webhooks

Opsætning af webhooks via shoppens administration
Du finder webhooks under Kontrolpanel > Webhooks

Hash key benyttes til at verificere indhold af webhooks når de leveres. For at se en log over seneste aktivitet for et bestemt webhook, klik på det blå forstørrelsesglas ikon (se mere omkring dette her). Du kan redigeret dit webhook via blyantikonet. Klik på "Opret webhook" for at konfigurere dit webhook:

Vælg Emne og indsæt den ønskede Adresse (URI). Angiv en passende titel:

Emner i administrationen versus emner/parametre i payload

Ordre oprettet svarer til orders/created
Ordre opdateret svarer til orders/updated
Ordre faktureret svarer til orders/invoice
Ordre afsendt (status ændring) svarer til orders/fulfilled
Ordre delvist afsendt (status ændring) svarer til orders/partially-fulfilled
Ordre annulleret (status ændring) svarer til orders/cancelled

 

Med Status er det muligt at aktivere og deaktivere et webhook:

 

Webhooks Log

Hvert webhook har en aktivitetslog. Du tilgår loggen via ikonet (det blå forstørrelsesglas) som findes i kolonnen Administration:

I loggen kan du, ud over status (Grøn = Succes, Rød = Fejl), se tidsstempel, URL og adresse, samt antal forsøg hvis levering af webhooket fejler –Se mere vedr. tidsintervaller her. Hvis levering er gennemført med et 200 OK status response (som beskrevet nærmere her) vil status for levering være markeret med "Success", hvilket også afspejles i første kolonne med et grønt ikon. Ellers vil denne kolonne stå som "Error" og linjen være markeret med rødt ikon. Adresse feltet (der udgør din "Target-URL" som shoppen poster til) kan fremsøges i søgefeltet, hvis du f.eks. ønsker at filtrere på dette:

 

Arbejde med webhooks

 

Test af webhooks

For at teste dit webhook bør du oprette en ordre og ændre status på denne, således at det event som du abonnerer på, bliver udløst. Du kan f.eks. køre din test fra en lokal server, eller benytte en service som Beeceptor mv. Hvis du benytter en lokal server, skal du være opmærksom på at denne skal gøres tilgængelig for kald udefra. Dette kan f.eks. gøres igennem services som Pagekite eller ngrok.

 

Webhook endpoints

For at en notifikation fra et webhook kan udløse en handling i din applikation, skal du opsætte et endpoint (destination) som dit webhook kan ramme. Dette endpoint skal være en HTTPS-adresse som kan håndtere notifikationer fra udløste events, som beskrevet i følgende afsnit.

 

Modtagelse af webhooks

Når du har konfigureret dit webhook, udløser Hostedshop en HTTP POST request til URI'en specificeret i feltet address på den pågældende webhook, hver gang handlingen som angivet i topic sker i shoppen.

 

Reaktion på et webhook

For at give til kende, at du har modtaget data fra et webhook, skal din applikation svare med et 200 OK status response. Et hvert response uden for 200 området, vil indikere at din applikation ikke har modtaget data. Bemærk: Ved levering af webhook følger vores system ikke redirects.

 

Når levering fejler

Når levering af et webhook fejler, forsøges levering gentaget efter 5 minutter. Når først levering af webhook er fejlet 20 gange over en 48 timers periode, bliver det deaktiveret. Følgende tabel angiver intervaller for leveringsforsøg:

#fejl gentagelses forsinkelse total forsinkelse
1 5 min 5 min
2 10 min 15 min
3 15 min 30 min
4 30 min 1 time
5 1 time 2 timer
6 1 time 3 timer
7 1 time 4 timer
8 1 time 5 timer
9 1 time 6 timer
10 2 timer 8 timer
11 2 timer 10 timer
12 2 timer 12 timer
13 3 timer 15 timer
14 3 timer 18 timer
15 4 timer 22 timer
16 4 timer 26 timer
17 4 timer 30 timer
18 6 timer 36 timer
19 12 timer 48 timer

Når først et webhook er blevet deaktiveret, vil det ikke længere blive udløst når handlingen som svarer til det emne den abonnerer på sker i shoppen. Genaktivering af et deaktiveret webhook foregår vis shoppens administration som beskrevet tidligere i artiklen, ved at sætte Status til aktiv.

 

Verificering af webhooks

For at højne sikkerheden i din applikation anbefales det at du verificerer, at det kald du får ind, også kommer fra den pågældende webshop. Notifikationer fra webhooks sendt fra shoppen er digitalt signeret med en secret key (hash key), som vises i toppen af webhooks siden i shoppens administration (Kontrolpanel > Webhooks). Signeringsnøglen er unik for shopløsningen som handlingen udløses fra og er den samme for alle webhooks der måtte være konfigureret på shoppen.

For at verificere at et request kommer fra Hostedshop, skal du beregne den BASE64-indkodede HMAC-streng i det request payload du modtager, og sammenligne denne med værdien i X-Hmac-Sha256 headeren.

  Følgende eksempel benytter PHP til at verificere et webhook request


    declare(strict_types = 1);

    \define('MY_SECRET_KEY', 'my-secret-key');

    function verifyWebhook($payload, $hmacHeader) : bool
    {
        $calculatedHMAC = \base64_encode(
        \hash_hmac('sha256', $payload, \MY_SECRET_KEY, true)
        );

        return \hash_equals($hmacHeader, $calculatedHMAC);
    }

    $providedHMAC = $_SERVER['HTTP_X_HMAC_SHA256'];
    $data = \file_get_contents('php://input');
    
    $verified = verifyWebhook($data, $providedHMAC);
    \printf('Webhook verified: %s', \var_export($verified, true));

  Følgende eksempel benytter Go til at verificere et webhook request


    import (
            "crypto/hmac"
            "crypto/sha256"
            "encoding/base64"
            "net/http"
    )

    const hmacHeader = "X-Hmac-Sha256"

    func verifyWebhook(payload, secretKey []byte, request *http.Request) (bool, error) {
         received := request.Header.Get(hmacHeader)
         receivedHMAC := []byte(received)

         hash := hmac.New(sha256.New, secretKey)
         hash.Write(payload)
         sum := hash.Sum(nil)

         encoded := base64.StdEncoding.EncodeToString(sum)
         calculatedHMAC := []byte(encoded)

         return hmac.Equal(receivedHMAC, calculatedHMAC), nil
    }