Webhooks

Introduction

  
Webhooks can be used to receive notifications about specific events in the shop. Webhooks allow your application to react to events immediately after they happen in the shop, instead of having to periodically retrieve data via the API. For example, you can use webhooks to trigger an action in your application when a customer creates an order, or when an order is shipped. By using webhooks, you can use fewer API calls overall, making your application more efficient and faster to update.

Webhooks content

After creating a webhook, you will - with every event containing the subject you have specified - receive a notification. This notification contains a JSON-encoded payload with relevant data and HTTPS headers that contain the topic for the notification.

In the body of the HTTP request is a JSON-encoded payload. Currently, only the ID of the affected element is supplemented (applies to both orders and products). For example, an orders/created notification for an order ID some-order-id will contain the following in its HTTP request body:

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

In addition to the information in the body, further information is supplemented with the following headers (in continuation of the example above):

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

This information can be used to enhance the functionality and security of your application.X-Hmac-Sha256 is used to verify webhooks, and X-Shop-Domain is used to identify the specific shop with which the triggered event is associated to.

Actions supported

The following is a complete list of supported actions, by category:

Category	Events
Orders	orders/cancelled, orders/created, orders/fulfilled, orders/invoice, orders/partially-fulfilled, orders/updated
Products	products/created, products/updated, products/delete

 

Configuring Webhooks

Setting up webhooks via the shop administration
You can find webhooks under Setiings > Webhooks:

If you haven't created any webhooks yet, you will see this page. Click "Create webhook":

Specify Name, choose which Event your webhook should respond to, and insert the desired Endpoint (The Endpoint field constitutes your "Target-URL" that the shop posts to):

Items in admin versus data in payload

In the dropdown list Event (actions) you have these options that reflect the following Payload:

Order created corresponds to orders/created
Order updated corresponds to orders/updated
Order invoiced corresponds to orders/invoice
Order sent (status change) corresponds to orders/fulfilled
Order partially shipped(status change) corresponds toorders/partially-fulfilled
Order cancelled (status change) corresponds to orders/cancelled

Once created, you can activate and deactivate your webhook directly from the overview:

History

If you click a title in the overview, the details for the webhook in question is shown, for example the number of retries if delivery of the webhook fails - See more about time intervals here. Click "History" to view the log for all your webhooks:
 

 

In the history, you can filter and search events and response codes. If the delivery is accomplished with status 200 (described in more detail here), status for a succesful delivery will be marked in the first column. In this example, we can see that the status is marked with a "404" error, which should be investigated further. Click "Payload" to preview what your webhook has in Payload:

In this example, we have created or webhook with the event "Order created" In the history, we see our first call, that contain the following payload: "Order created ".
 

 

Payload displays the order number of the order that triggered our webhook.

 

Working with webhooks

Testing webhooks

To test your webhook, you should create an order and change the status on the order, so that the event that you subscribe to gets triggered. You can for example run your test from a local server or use a service like Beeceptor, etc. If you use a local server, note that the server must be made available for external calls. This can for example be accomplished through services like Pagekite or ngrok.

Webhook endpoints

In order for a notification from a webhook to trigger an action in your application, you need to set up an endpoint (destination) that your webhook can hit. This endpoint must be a HTTPS-address that can handle notifications from triggered events, as outlined in the following sections.

Receiving webhooks

Once you have configured your webhook, Dandomain Webshop triggers an HTTP POST request to the URI specified in the field addresson that webhook whenever the action specified in topic happens in the shop.

Reaction on a webhook

To indicate that you have received data from a webhook, your application must respond with a 200 OK status response. Any response outside the 200 range will indicate that your application has not received data.
Note: Webhooks have a timeout on 5 seconds. When delivering webhooks, our system does not follow redirects.

When delivery fails

When delivery of a webhook fails, a new delivery attempt is made after 5 minutes. The following table indicates the timeframe for delivery attempts:

#error	repeat delay	total delay
1	5 min	5 min
2	10mins	15mins
3	15mins	30mins
4	30mins	1hrs
5	1hrs	2hrs
6	1hrs	3hrs
7	1hrs	4hrs
8	1hrs	5hrs
9	1hrs	6hrs
10	2hrs	8hrs
11	2hrs	10hrs
12	2hrs	12hrs
13	3hrs	15hrs
14	3hrs	18hrs
15	4hrs	22hrs
16	4hrs	26hrs
17	4hrs	30hrs
18	6hrs	36hrs
19	12hrs	48hrs

When a webhook delivery has failed 20 times in a 48-hour period, no further attempts are made. 

Verification of webhooks

To increase the security of your application, it is recommended that you verify that the call you receive is from the webshop in question. Notifications from webhooks sent from the shop has been signed digitally signeret with a secret key (Token), which can be accessed by clicking "Token":

The secret key is unique for the shop solution that the action is triggered from, and the key is the same for all webhooks configured in the shop:

To verify that a request comes from the Hostedshop system, you need to calculate the BASE64-encoded HMAC-string in the request payload you recieve, and compare it with the value in the X-Hmac-Sha256 headeren.

PHP exampleGo example

 The following example uses PHPto 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    }