Webhooks

In some cases, the consumer does not return to the webshop (in the case of bank transfer, the payment will always be decoupled), and another way of checking the current status of the order needs to be used. It is possible to periodically retrieve the order and check whether the status was changed, but this is inefficient and cumbersome.

To solve this, webhooks can be used. A webhook is a callback (HTTP POST) to a merchant-supplied URL. The URL is configurable per project in the webhook_url field. The order ID and project ID are available in the body of the request. EMS Online makes the request whenever the status of an order changes.

Example webhook from EMS Online to http://www.example.com/webhook:

POST /webhook HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "event": "status_changed",
  "order_id": "4c6afd74-a840-4aab-b411-1e6e0636d341",
  "project_id": "b5f39273-44e7-4385-8e08-44612ef3e117"
}

Webhooks can be configured on project level, but can be overwritten for a specific order by supplying a webhook url when creating the order. For this specific order the specific webhook url will be used. This is part of the order schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Order",
  "type": "object",
  "properties": {
    "id": {
      "description": "Order identifier",
      "type": "string",
      "readOnly": true
    },
    "webhook_url": {
      "description": "Used for transaction updates",
      "type": "string",
      "format": "uri"
    }
  }
}

Retries

When a call to the provided webhook_url results in a 4xx or 5xx http status code the message will be delivered again. If it is unable to deliver the message for the 10th time it will stop delivery. The retries are two minutes apart.