App Developer

Webhooks

When you submit an app in the app store, you can specify a webhook URL that we call when changes to data happens on a shop that has your app installed. The kind of notifications you receive depends on what your app has Read access to. If it has read access to products, it will receive product-related change notifications.

Sections in article
Callback
Authenticity
App Components

Entity events

The following event types will trigger a call to your webhook URL

Product

• Delete
• Create
• Update
  • If any of this data changes
    • Product number
    • Vendor number
    • Weight
    • Stock count
    • Stock limit
    • EAN/Barcode
    • Sort order
    • Minimum buy amount
    • Minimum buy amount B2B
    • Maximum buy amount
    • File sales link
    • Is variant master
    • Notes
    • Google taxonomy category
    • Rate variant products
    • Review variant products
    • Is gift certificate
    • Prices []
      • Amount (quantity)
      • Currency code
      • B2B group
      • Unit price
      • Special offer price
      • Special offer period id
      • Gains percentage (avance)
    • Media (more images) []
      • Name
      • Alt text
      • URL
      • Mime type
      • Sort order
      • Thumbnail

Orders

• Delete
• Create
• Update
  • If any of this data changes
    • Incomplete
    • Total price
    • Total weight
    • Transaction number
    • Shipping fee
    • Shipping fee includes vat
    • Shipping method ID
    • Payment fee
    • Payment fee includes vat
    • Payment method ID
    • Order comments
    • Customer comments
    • Order state ID
      • Delivery info
        • Phone
        • Address
        • Address2
        • Name
        • Company name
        • City
        • Country
        • EAN
        • Email
        • State
        • Zip code
      • Customer info
        • Phone
        • Address
        • Address2
        • Name
        • Company name
        • City
        • Country
        • EAN
        • Email
        • State
        • Zip code
      • Invoice info
        • Credit note number
        • Invoice date
        • Is payed
        • Invoice number
        • Invoice state

Customers

• Delete
• Create
• Update

Callback

The data we send to you will consist of an array of “changes” that have occured. Typically there will only be one change in this array, but since we may occasionally bulk events, your system must be able to handle several changes per request.

Each change consists of a string array of fields that have changed, a version of the change (more on that further down this documentation), and a “newValues” and an “oldValues” object representing how the object looked before and after.

To determine what kind of data has changed, we also send a “objectType” field which describes what kind of entity have been changed

An identifier (called “objectIdentifier”) will always be included for the data that has changed as well. For instance, if the data is a product, that ID will be the product number.

Example: Update

In update changes, both “newValues” and “oldValues” is present.

Note also that “<FieldName>Delta” fields are included in “newValues”. These fields are unique to “update”-related changes, but can have a significant impact on the stability of your webhook URL implementation. For more information, see the “Idempotence” section.

[
  {
    "propertiesChanged": [
      "minBuyAmount",
      "maxBuyAmount",
      "notes",
      "stockCount"
    ],
    "oldValues": {
      "objectIdentifier": "my-fancy-product-number",
      "minBuyAmount": 3,
      "maxBuyAmount": 7,
      "notes": "chuck norris",
      "stockCount": 1337
    },
    "newValues": {
      "objectIdentifier": "my-fancy-product-number",
      "minBuyAmount": 1, 
      "minBuyAmountDelta": -2,
      "maxBuyAmount": 13, 
      "maxBuyAmountDelta": 6,
      "notes": "foobar",
      "stockCount": 1242, 
      "stockCountDelta": -95
    },
    "objectType": "Product",
    "version": 1
  }
]

Example: Create

In create changes, only “newValues” is present, and “oldValues” is null.

[
  {
    "propertiesChanged": [
      "minBuyAmount",
      "maxBuyAmount",
      "notes",
      "stockCount"
    ],
    "oldValues": null,
    "newValues": {
      "objectIdentifier": "my-fancy-product-number",
      "minBuyAmount": 1, 
      "maxBuyAmount": 13, 
      "notes": "foobar",
      "stockCount": 1242
    },
    "objectType": "Product",
    "version": 1
  }
]

Example: Delete

In delete changes, only “oldValues” is present, and “newValues” is null.

[
  {
    "propertiesChanged": [
      "minBuyAmount",
      "maxBuyAmount",
      "notes",
      "stockCount"
    ],
    "oldValues": {
      "objectIdentifier": "my-fancy-product-number",
      "minBuyAmount": 1, 
      "maxBuyAmount": 13, 
      "notes": "foobar",
      "stockCount": 1242
    },
    "newValues": null,
    "objectType": "Product",
    "version": 1
  }
]

Authenticity

How to verify that the webhook url is requested by the DanDomain webhooks system and not some other system ? And that the body content have not been altered by other systems.

When a hook is fired against the hook url, the request will always contain a http header called  x-webhook-signature.
The x-webhook-signature will contain a HMAC signature of the payload send in request body.
This HMAC can be used by the receiver of the hook to verify the validity of the hook.

This should be done by the receiver, by comparing the value of the x-webhook-signature header with a HMAC computed by the receiver.
The hook request should only be trusted if these values are equal.

To calculate the HMAC of the hook body on the receiver end, create a HMACSHA512 of the hook body using the hook secret. And make sure to base64 encode this hash.

C# example

var encoding = Encoding.UTF8;
var keyByte = encoding.GetBytes(secret);
var messageBytes = encoding.GetBytes(message);
using (var hmac = new HMACSHA512(keyByte))

{ var hashmessage = hmac.ComputeHash(messageBytes); hashmessage = Convert.ToBase64String(hashmessage); }

HMAC secret

Secrets can be generated using the admin panel, but be sure to notice that changing a secret will mean you need to change secret used for HMAC in the reciever

App Components

App uninstall flow

[SHOPHOST]/admin/WebAPI/Endpoints/v1_0/PluginService/help

[SHOPHOST] /admin/WebAPI/Endpoints/v1_0/PluginService.svc