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 (applies to both orders and products). 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.

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 60 minutes. The following table describes the schedule for automated retry attempts:

Once delivery of a webhook has failed 9 times over a 24 hour period, no further tries will be performed.

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
    }