FEEDBACK
X
FEEDBACK

Er du tilfreds med indholdet i denne her guide?

Hvis ikke, så vil vi meget gerne høre dine kommentarer.

Skriv dem herunder, så gør vi det bedste, vi kan for at forbedre manualen.

Tak for din kommentar!

Send ny?

Dansk English

SmartWeb Help | API

Webhooks

Introduction

   Webhooks are used to receive notifications about specific events occurring in the shop system. Webhooks allow your application to act in response to events immediately after they occur in the shop, instead of having to periodically poll the API for status changes. For example, you can rely on webhooks to trigger an action in your application when a customer creates an order or when an order is fulfilled. By using webhooks you can make fewer API calls overall, which ensures that your apps are more efficient with a fast response time.

 

Webhooks content

After creating a webhook, whenever an event with the topic specified occurs in the shop system, you'll receive a notification. This notification contains a JSON payload with relevant data and HTTP headers that provide the context for the notification.

The body of the HTTP request contains a JSON encoded payload. Currently all webhook notifications exclusively provide an ID of the affected element. For example, given an orders/created notification for an order with ID some-order-id, the body of the HTTP request would be:

 

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

 

In addition to the body of the request, additional information is provided with the following headers (in continuation of the above example):

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

You don't need to use this information, but it can improve the functionality and security of your application. For example, X-Hmac-Sha256 is used to verify webhooks and X-Shop-Domain is used to identify the shop to which the event that triggered the webhook is associated.

 

List of supported topics

The following is a complete list of supported topics, by category.

Category Topics
Orders orders/cancelledorders/createdorders/fulfilledorders/invoiceorders/partially-fulfilledorders/updated

 

Configuring webhooks

Information on how to set up webhooks in the administration.
You will find webhooks in the shop administration under Control panel > Webhooks

The Hash key is used to identify webhooks when delivered. You can view the latest webhook activity by clicking the blue magnifying glass icon. Edit webhooks via the pencil icon. Click the the "Create webhook" button to create a new webhook as shown on the following screen shots:

Select a Topic and insert the desired Address (Target-URL). Set an associated title:

 

Topics in the shop administration versus topics/parameters in the payload

Order created equals orders/created
Order updated equals orders/updated
Order invoiced equals orders/invoice
Order sent (status change) equals orders/fulfilled
Order partially sent (status change) equals orders/partially-fulfilled
Order cancelled (status change) equals orders/cancelled

 

Use the Status checkbox to enable and disable webhooks:

 

Webhooks Log

Each webhook has an associated activity log. You access the log via the magnifying glass icon found in the Administration column:

The log will display a status icon (Green = Success, Red = Error) along with a timestamp, URL, Target-URL and retry count (view more about retry intervals here). A successful webhook delivery by 200 OK status response (as described in detail here) will be marked as "Success" with a green icon for the current event. Failed deliveries will be marked with "Error". It is possible to filter events by search, if you need to see events for a specific Target-URL etc.:

 

Working with webhooks

 

Testing webhooks

To test your webhook create an order and change its status to trigger the event that you are subscribing to. You can run your test from a local server or use a service like Beeceptor etc. Please note that when using a local server, you have to make this reachable from outside your local network. This can be done through services like Pagekite or ngrok.

 

Webhook endpoints

To make a notification from your webhook trigger an event in your application, you must set up an endpoint (destination) for your webhook to target. This endpoint must be a HTTPS address that can handle notifications from triggered events as described in the following section.

 

Receiving webhooks

When your webhook is configured, the system will trigger a HTTP POST request to the URI specified i the address field, every time the event specified in the webhook topic is raised in the shop system.

 

Reacting on a webhook

To acknowledge that you have received data from your webhook, your application must answer with a 200 OK status response. Any response outside the range of 200 will indicate that your application did not receive any data. Please note: when delivering webhooks our system does not follow redirects.

 

When delivery fails

When delivery of a webhook fails, delayed retries will be issued every 5 minutes. When 20 delivery attempts have been unsuccessful over a 48 hour period, the webhook will be deactivated automatically. The following table describes the schedule for automated retry attempts:

#failures retry delay total delay
1 5 min 5 min
2 10 min 15 min
3 15 min 30 min
4 30 min 1 hour
5 1 hour 2 hours
6 1 hour 3 hours
7 1 hour 4 hours
8 1 hour 5 hours
9 1 hour 6 hours
10 2 hours 8 hours
11 2 hours 10 hours
12 2 hours 12 hours
13 3 hours 15 hours
14 3 hours 18 hours
15 4 hours 22 hours
16 4 hours 26 hours
17 4 hours 30 hours
18 6 hours 36 hours
19 12 hours 48 hours

When a webhook enters disabled state it will no longer be triggered when the event it subscribes to is raised in the shop system. Reactivation of a deactivated webhook is done though the shop administration as described earlier in this article by setting the Status checkbox.

 

Verifying webhooks

To improve the security of your application, it is recommended that you verify a webhook was actually sent by the expected shop system. Webhook notifications sent by our system is digitally signed using the secret key (hash key) displayed at the top of the Webhooks page accessible via the Control panel > Webhooks menu in the shop administration. The secret key is unique to the solution that the event originated from and is the same for all webhooks configured for that particular solution.

To verify that the request from a webhook came from the shop system, calculate the BASE64 encoded HMAC digest of the request payload using your secret key, and compare it to the value in the X-Hmac-Sha256 header.

 

The following example uses PHP to verify a 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));

 

The following example uses Go to verify a 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
    }