Requirements and structure

If you want information about your shipments, orders and drafts sent to your own system continuously, you can create webhooks to enable this.

Endpoint requirements

To receive messages about your shipments, orders and drafts using webhooks, it is important that the endpoint specified in the setup handles the messages accordingly.

There are some requirements for the endpoint being set up. If these are not met, it will not be possible either to create a webhook or read the messages that are sent to it. The requirements are described in the following points:

Supports HTTPS

The endpoint set up is required to use a valid SSL/TLS certificate to ensure the integrity of the data sent to the endpoint.

Decrypt and process JWT data

The data sent to the endpoint will consist of a JSON object with a key "data". The value of this key will be an encrypted version of the data for a shipment, order or draft in your Shipmondo account as it stands after the action, that triggered the message, has been taken.

When creating a webhook in Shipmondo, you must enter a key. This key is used in Shipmondo to encrypt the data to be sent, while at the endpoint it is used to decrypt the data.

We use JWT to encrypt the data with the HS256 algorithm. It is therefore important that the endpoint defined uses the same algorithm and key to decrypt the value of the "data" key.

The endpoint returns an answer with a status of 200 within 3 seconds

When we send a message to the endpoint, it is required that a reply with status code 200 is returned within 3 seconds. If this is not the case, the connection will expire and the message will not be delivered. It's therefore recommended that data processing is limited as far as possible at the endpoint to which the message is sent in order to keep the response time low.

Message structure

The messages are made up of two parts. The first part of the message is headers, which contain information regarding the origin and trigger of the message, while the second part is the body of the message, which contains the encrypted data around the object itself that has been changed.

Headers

In the webhook message headers, you will find five custom headers from Shipmondo, which contain further information about the origin of the message. The five custom headers are as follows:

1. SMD-Resource-Type: contains information about which resource the webhook that created the message is using
2. SMD-Resource-Id: contains information about the ID value of the specific object that the message contains
3. SMD-Webhook-Id: contains information about the ID value of the webhook to which the message was sent
4. SMD-Action: contains information about which action triggered the message
5. SMD-User: contains information about which user performed the action that triggered the message

Body

The body of the message is a JSON object that contains a key "data", which has an encrypted value.

An example of what the body of the message can look like can be seen here:

{
    "data": "eyJhbGciOiJIUzI1NiJ9.IntcIndlYmhvb2tcIjpcIldlYmhv..."
}

When you use JWT with HS256 on the value for "data", you get an object that contains the following information:

Webhook: the name of the webhook that sent the message

data: data body with a JSON object that corresponds to what you would get if you called the resource's GET endpoint through Shipmondo's API

URL: the URL of the endpoint to which the message was sent

An example of the above decrypted body can be seen here:

{
    "webhook":"Webhook1",
    "data": {
        "id": 119175,
        "order_id": "2042",
        "ordered_at ": "2021-02-22T11:41:08.000+01:00",
        "order_status ": "on_hold ",
        "fulfillment_status ": "unfulfilled"
        ....
    },
    "url": "https://example.com/webhook"
}