Shipping

Welcome to the Montonio Shipping API Developer Documentation.

Here you can find instructions on how to integrate with Montonio Shipping.

Production Only

To access the shipping API, you will need to use production keys. Production keys will become available once you sign an agreement for either one of our services.

For the shipping API specifically, production keys can also be used for testing purposes since no real costs are involved without sending actual packages.

Activating Shipping Providers

In order to be able to pass data to shipping providers, Montonio also requires credentials to their respective APIs. In order to activate a shipping provider, navigate to the Shipping page and select the Providers tab.

Under the Providers tab, you can select which provider to enable for your store and enter their respective credentials.

Note

If you do not have credentials for a shipping provider, you can register with their respective e-service in order to obtain them. For more info, contact the specific service provider.

Using the API

The API base URL for all endpoints is https://api.shipping.montonio.com.

All the endpoints provided in this documentation require authorization in the form of a JSON Web Token (JWT) in the Authorization header as a bearer token.

Generating the Token

The JWT used for authorization must contain your Access Key and be signed with your Secret Key using HMAC SHA256 (HS256). The exact implementation of how to generate the JWT varies by programming language and you can see some examples on the code panel.

Note

We recommend using popular community maintained libraries for JWT generation. You can browse the libraries for your programming language on the jwt.io website.

Show / Hide Parameters

Headers

Key	Required	Type	Description
alg	yes	string	Must be set to HS256
typ	yes	string	Must be set to JWT

Payload

Key	Required	Type	Description
access_key	yes	string	Your Access Key obtained from the Partner System.
exp	yes	number	Expiration time of the token in Unix time. Set that to 1 hour from the time of issuing the token.

Show / Hide Code Examples

JavaScript

/**
 * We recommend using the jsonwebtoken package to generate
 * Json Web Tokens. You can install it with npm:
 * > npm install jsonwebtoken
 * More information can be found at
 * https://www.npmjs.com/package/jsonwebtoken
 */
const jwt = require('jsonwebtoken');

const payload = {
    access_key: 'merchant_access_key'
}

const token = jwt.sign(
    payload,
    'merchant_secret_key',
    { algorithm: 'HS256', expiresIn: '1h' }
);

console.log(token);
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

PHP

<?php
/**
 * We recommend using Firebase's php-jwt package to generate
 * Json Web Tokens. You can install it with composer:
 * > composer require firebase/php-jwt
 * More information can be found at
 * https://github.com/firebase/php-jwt
 */
use \Firebase\JWT\JWT;

$payment_data = array(
    'access_key' => 'merchant_access_key',
    'iat'        => time(),
    'exp'        => time() + (60 * 60)
);

$payment_token = \Firebase\JWT\JWT::encode($payment_data, 'merchant_secret_key', 'HS256');

echo $payment_token;
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

?>

Python

'''
We recommend using the PyJWT package to generate
Json Web Tokens. You can install it with pip:
> pip3 install PyJWT datetime
More information can be found at
https://pyjwt.readthedocs.io/en/latest/
'''
import jwt
from datetime import datetime, timedelta, timezone

payment_data = {
    'access_key': 'merchant_access_key',
    'iat': datetime.now(timezone.utc),
    'exp': datetime.now(timezone.utc) + timedelta(hours=1)
}

payment_token = jwt.encode(
    payment_data,
    'merchant_secret_key',
    algorithm='HS256'
).decode('utf-8')

print(payment_token)
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

Displaying the List of Available Pickup Points

Example request header:

  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

Example request

curl -X GET \
  'https://api.shipping.montonio.com/pickup-points' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoiOTZlNjhlZDEtMDkzOC00NTE0LWFkZDEtYmE1MGE0NmI3YWZkIiwiaWF0IjoxNjAzNzE1MjczLCJleHAiOjE2MDM3MTg4NzN9.LpSPYEtkRd5Ze4RZoeN8rRs6hzNP1cqw_Th8x4oRCXo'

Show / Hide Response Data

{
    "EE": {
      "providers": {
        "omniva": {
          "post_office": [
            {
              "uuid": "23219ba9-e4af-4416-acfd-938cff0296e8",
              "name": "Aseri postipunkt",
              "country": "EE",
              "type": "post_office",
              "provider_name": "omniva",
              "region": "Lääne-Viru maakond",
              "locality": "Viru-Nigula vald"
            },
            {
              "uuid": "542e3e42-79dc-42e6-8a50-9d90fc09da13",
              "name": "Avinurme postipunkt",
              "country": "EE",
              "type": "post_office",
              "provider_name": "omniva",
              "region": "Jõgeva maakond",
              "locality": "Mustvee vald"
            }
          ],
          "parcel_machine": [
            {
              "uuid": "5a3239e8-9ce6-439c-8a3b-f8d8f3611149",
              "name": "Ahtme Maxima XX pakiautomaat",
              "country": "EE",
              "type": "parcel_machine",
              "provider_name": "omniva",
              "region": "Ida-Viru maakond",
              "locality": "Kohtla-Järve linn"
            },
            {
              "uuid": "c479703b-9632-4704-b962-1742ef8609bb",
              "name": "Antsla Coop Konsumi pakiautomaat",
              "country": "EE",
              "type": "parcel_machine",
              "provider_name": "omniva",
              "region": "Võru maakond",
              "locality": "Antsla vald"
            }
          ]
        },
        "itella": {
          "parcel_machine": [
            {
              "uuid": "ea15bc94-e6c2-467d-b537-740fdf199991",
              "name": "Tammiste Konsum (valge)",
              "country": "EE",
              "type": "parcel_machine",
              "provider_name": "itella",
              "region": null,
              "locality": "Tammiste"
            },
            {
              "uuid": "9845fe06-e0cd-4702-aa82-85c169f654c2",
              "name": "Jõhvi Pargi keskus (valge)",
              "country": "EE",
              "type": "parcel_machine",
              "provider_name": "itella",
              "region": null,
              "locality": "Jõhvi"
            }
          ]
        }
      }
    },
    "LV": {
      "providers": {
        "omniva": {
          "parcel_machine": [
            {
              "uuid": "1359dcb4-9933-4c6d-8c71-8a6118cd9d2d",
              "name": "Aizkraukles T/C Iga pakomāts",
              "country": "LV",
              "type": "parcel_machine",
              "provider_name": "omniva",
              "region": "Aizkraukles novads",
              "locality": "Aizkraukle"
            }
          ]
        }
      }
    },
    "LT": {
      "providers": {
        "omniva": {
          "parcel_machine": [
            {
              "uuid": "f97d1d8c-6aa3-4da4-a44e-25136da64efb",
              "name": "Alytaus IKI Jaunimo paštomatas",
              "country": "LT",
              "type": "parcel_machine",
              "provider_name": "omniva",
              "region": "Alytaus apskr.",
              "locality": "Alytaus m. sav."
            }
          ]
        }
      }
    },
    "FI": {
      "providers": {
        "itella": {
          "parcel_machine": [
            {
              "uuid": "e33d7914-5149-4863-865a-5d33abc43ac8",
              "name": "R-kioski Pohjois-Haaga",
              "country": "FI",
              "type": "parcel_machine",
              "provider_name": "itella",
              "region": null,
              "locality": "HELSINKI"
            }
          ]
        }
      }
    }
}

GET /pickup-points

In order to use a pickup point service (parcel machines or post offices), you need to fetch the list of available pickup points from our API. Each pickup point has a unique UUID string that must be included when creating a shipment using that pickup point.

The endpoint returns pickup points grouped by country, provider and type (parcel machine or post office). Note that only the pickup points from providers that have been activated in the partner system will be returned.

Note

We recommend caching the list of pickup points to avoid too many unnecessary requests to our API. It is recommended to update pickup points once every 24 hours.

URL

https://api.shipping.montonio.com/pickup-points

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Creating a shipment

POST /shipments

This endpoint is used to create a shipment in the Montonio Partner System and register it with the given service provider. This can be done at any point after the customer has completed their order.

To create a shipment without waiting for response, use /shipments/create-async endpoint instead. This will immediately return an empty body with the status code 201 and attempt to register the shipment in the background. This is useful if you want to minimalize the wait time for customer after completing checkout.

Example request header::

  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

Show / Hide Example Request

curl -X POST \
  'https://api.shipping.montonio.com/shipments' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoiOTZlNjhlZDEtMDkzOC00NTE0LWFkZDEtYmE1MGE0NmI3YWZkIiwiaWF0IjoxNjAzNzE1MjczLCJleHAiOjE2MDM3MTg4NzN9.LpSPYEtkRd5Ze4RZoeN8rRs6hzNP1cqw_Th8x4oRCXo'
  -d '{
    "shipping_method": "dpd_parcel_machines",
    "pickup_point_uuid": "736750c9-e793-4ef1-b923-0268dd6492fd",
    "merchant_reference": "95",
    "sender_name": "Montonio OÜ",
    "sender_phone_country": "372",
    "sender_phone_number": "55512345",
    "sender_street_address_1": "Test address 123",
    "sender_street_address_2": "45",
    "sender_locality": "Tallinn",
    "sender_region": "Harjumaa",
    "sender_postal_code": "12345",
    "sender_country": "EE",
    "shipping_first_name": "John",
    "shipping_last_name": "Smith",
    "shipping_company": "Test Company OÜ",
    "shipping_street_address_1": "Test street 234",
    "shipping_street_address_2": "56-B",
    "shipping_locality": "Tartu",
    "shipping_region": "Tartumaa",
    "shipping_postal_code": "11111",
    "shipping_country": "EE",
    "shipping_email": "test@example.com",
    "shipping_phone_country": "372",
    "shipping_phone_number": "5555555",
    "billing_first_name": "John",
    "billing_last_name": "Smith",
    "billing_company": "Test Company OÜ",
    "billing_street_address_1": "Test street 234",
    "billing_street_address_2": "56-B",
    "billing_locality": "Tartu",
    "billing_region": "Tartumaa",
    "billing_postal_code": "11111",
    "billing_country": "EE",
    "billing_email": "test@example.com",
    "billing_phone_country": "372",
    "billing_phone_number": "5555555",
    "currency": "EUR",
    "shipping_total": 1.50,
    "total": 25.90,
    "parcels": [
        {
            "weight": 1.02
        }
    ]
  }'

Example response:

{
  "uuid": "d682bfd5-6ea3-4b70-bb59-bc5b009dddd2",
  "shipping_method": {
    "uuid": "0980e92b-ab97-48d3-af3b-1aabc987b4d9",
    "identifier": "dpd_parcel_machines",
    "name": "DPD pickup points",
    "provider_name": "dpd",
    "type": "parcel_machine",
    "available_in_countries": [
      "EE",
      "LV",
      "LT"
    ]
  },
  "currency": "EUR",
  "shipping_total": "1.50",
  "total": "25.90",
  "billing_first_name": "John",
  "billing_last_name": "Smith",
  "billing_company": "Test Company OÜ",
  "billing_street_address_1": "Test street 234",
  "billing_street_address_2": "56-B",
  "billing_locality": "Tartu",
  "billing_region": "Tartumaa",
  "billing_postal_code": "11111",
  "billing_country": "EE",
  "billing_email": "test@example.com",
  "billing_phone_number": "5555555",
  "shipping_first_name": "John",
  "shipping_last_name": "Smith",
  "shipping_company": "Test Company OÜ",
  "shipping_street_address_1": "Test street 234",
  "shipping_street_address_2": "56-B",
  "shipping_locality": "Tartu",
  "shipping_region": "Tartumaa",
  "shipping_postal_code": "11111",
  "shipping_country": "EE",
  "shipping_email": "test@example.com",
  "shipping_phone_number": "5555555",
  "payment_method": null,
  "merchant_reference": "95",
  "sender_name": "Montonio Finance OÜ",
  "sender_phone_number": "55512345",
  "sender_street_address_1": "Test address 123",
  "sender_street_address_2": "45",
  "sender_locality": "Tallinn",
  "sender_region": "Harjumaa",
  "sender_postal_code": "12345",
  "sender_country": "EE",
  "error_reason": null,
  "duplicate_shipment_sort_order": 158
}

URL

https://api.shipping.montonio.com/shipments

https://api.shipping.montonio.com/shipments/create-async

Show / Hide Parameters

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Body

Key	Required	Data type	Notes	Example Value
merchant_reference	yes	string	The order reference in the merchant’s system (e.g. the order ID). Note that this will also be included on the shipping label.	"1001"
sender_name	yes	string	The company name for return address	"Montonio Finance OÜ"
sender_phone_number	yes	string	The phone number of return addressee (without country code). Can be with country code if sender_phone_country is empty	"55512345"
sender_street_address_1	yes	string	The first line of return street address	"Test address 123"
sender_locality	yes	string	The city or town for return address	"Tallinn"
sender_postal_code	yes	string	The postal code for return address	"12345"
sender_country	yes	string	The two-letter code for return address country	"EE"
shipping_first_name	yes	string	The first name from customer’s shipping info	"John"
shipping_phone_number	yes	string	The customer’s shipping phone number (without country code). Can be with country code if shipping_phone_country is empty	"55512345"
parcels	yes	array	An array of objects containing data for each parcel to be sent (should include exactly one object if sending whole order as one package), see below	[{...}, {...}]
shipping_method	no	string	A string value specifying which provider and method is being used. If not provided, will only create the shipment in Montonio Partner System, but won’t register with provider. Currently accepted values: omniva_parcel_machines, omniva_post_offices, omniva_courier, itella_parcel_machines, itella_post_offices, itella_courier, dpd_parcel_machines, dpd_courier, venipak_courier, venipak_parcel_shop, venipak_parcel_machines	"omniva_parcel_machines"
pickup_point_uuid	no	string	The unique id used to identify the pickup point on our end. Required if shipping method is not courier.	"23219ba9-e4af-4416-acfd-938cff0296e8"
sender_phone_country	no	string	The country code of return addressee’s phone	"372"
sender_street_address_2	no	string	The second line of return street address	"45"
sender_region	no	string	The region for return address	"Harjumaa"
shipping_last_name	no	string	The last name from customer’s shipping info	"Smith"
shipping_company	no	string	The company name from cusomer’s shipping info	"Montonio Finance OÜ"
shipping_street_address_1	no	string	The first line from customer’s shipping address. Required if sending via courier	"Test address 123"
shipping_street_address_2	no	string	The second line from customer’s shipping address	"45"
shipping_locality	no	string	The city or town from customer’s shipping address. Required if sending via courier	"Tallinn"
shipping_region	no	string	The region from customer’s shipping address	"Harjumaa"
shipping_postal_code	no	string	The postal code from customer’s shipping address. Required if sending via courier	"12345"
shipping_country	no	string	The two-letter country code representing customer’s shipping country. Required if sending via courier	"EE"
shipping_email	no	string	The customer’s shipping e-mail	"test@example.com"
shipping_phone_country	no	string	The country code of customer’s shipping phone number	"372"
billing_first_name	no	string	The first name from customer’s billing info	"John"
billing_last_name	no	string	The last name from customer’s billing info	"Smith"
billing_company	no	string	The company name from cusomer’s billing info	"Montonio Finance OÜ"
billing_street_address_1	no	string	The first line from customer’s billing address	"Test address 123"
billing_street_address_2	no	string	The second line from customer’s billing address	"45"
billing_locality	no	string	The city or town from customer’s billing address	"Tallinn"
billing_region	no	string	The region from customer’s billing address	"Harjumaa"
billing_postal_code	no	string	The postal code from customer’s billing address	"12345"
billing_country	no	string	The two-letter country code representing customer’s billing country	"EE"
billing_email	no	string	The customer’s billing e-mail	"test@example.com"
billing_phone_country	no	string	The country code of customer’s billing phone number	"372"
billing_phone_number	no	string	The customer’s billing phone number (without country code). Can be with country code if billing_phone_country is empty	"55512345"
currency	no	string	The three-letter currency code used for given order	"EUR"
shipping_total	no	number	The total shipping cost for given order (up to 2 decimal places)	1.50
total	no	number	The total cost of the given order, including shipping (up to 2 decimal places)	25.90

Body: Parcel object

Key	Required	Data type	Notes	Example Value
weight	yes	number	Weight of parcel in kg (up to 2 decimal places). Can be 0 if unknown. Refer service providers’ home pages for info on weight limits for different services.	1.02

Note

If there is an error when registering the shipment with the provider, the shipment will still be created in Montonio Partner System. There you can see the error message and duplicate the shipment to manually change data and try again.

Printing shipment labels

POST /shipments/label-from-store

This endpoint is used to print labels for one or more shipments that have been successfully registered with their respective shipping providers. It returns a download link to a PDF file containing all the shipping labels for specified shipments.

Example request header::

  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

Example request

curl -X POST \
  'https://api.shipping.montonio.com/shipments/label-from-store' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoiOTZlNjhlZDEtMDkzOC00NTE0LWFkZDEtYmE1MGE0NmI3YWZkIiwiaWF0IjoxNjAzNzE1MjczLCJleHAiOjE2MDM3MTg4NzN9.LpSPYEtkRd5Ze4RZoeN8rRs6hzNP1cqw_Th8x4oRCXo'
  -d '{
    "merchant_references": [
      "1001",
      "1002",
      "1005"
    ]
  }'

Example response:

{
  "url": "https://s3.eu-central-1.amazonaws.com/data.tmp.montonio.com/labels-45adfe1f-0bc4-4fb4-ba5d-0d9299c7c809.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIATGBFH3FPJMSLH65C%2F20220502%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20220502T131030Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEH0aDGV1LWNlbnRyYWwtMSJIMEYCIQDpitxXwQe9UEWEcNCd9ESdYjoX3VhYP%2BsyWXfLgxoz9gIhAMzz8X5KhNa%2BGY0fJvuhJkc6l3H1TVibCX2fzJU%2F3GQRKpgCCEYQAxoMMjE5MTIxNDQxMTE4IgywQpuao9j7vRC41wsq9QG0bSP6DkRE%2BkKssNrYdBnPzfBf27UI7nS4jJSBwJfW3TOeGGUTj9TkK39QiXeH1u6bx9gDWQMinmG4y%2FcHmcjumC%2FSLcPSnvDe6GFq4ppqnhMvhBhA07ekINO20u58RCuQfVokuL70YNvMCF%2FZHpgCqShxJj3mJFvSb%2BSW5lpHPCB9qs7g7pTDvGfhfmCc7NP4dNIvb657F%2FBI13enxRDzItbCfd3GgOcZ5Fx0lvyQLN1HhDcbyqG%2FaBQoJ3bNEPUH4vezjFwxr1yoUXNW8BhbX2veYPqkNxJVAVxB4wP6YisY4bLKtyB8X%2FQ9UbwXz%2Fq%2BYT36rzDDsL%2BTBjqZAYUrGee3YY4KP%2Fn1ENvHhzWHXEW4UX1LJE%2FMvews1%2B9njaduEctyrJaR4CbiQ5FiiOzZCsqCF8Za8hUp20p1ZGwVpe3p2ldkscCB1fuPDiGR0rNDk62iFq3lmCoF359BPdaGT1VbJsX6lxO0LBL5Ze5sbb%2FB6Qz%2FO3ITDplJMvZUu0muGaAyDHTFMDzAadVB75kX%2FRKDPO9OVQ%3D%3D&X-Amz-Signature=96fe358ca057adce8919c5702a055e207220c8e733dd7176357355f8cf2d4743"
}

URL

https://api.shipping.montonio.com/shipments/label-from-store

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Body

Key	Required	Data type	Notes	Example Value
merchant_references	yes	array	An array of related orders’ reference strings in your store. These will be used to match partner system shipments to your store orders when printing labels.	["1001", "1005"]

Registering a webhook

PATCH /stores/store-webhook

This endpoint is used to register a webhook we can call on certain events. Currently it is used for two events: when a shipment is successfully registered with shipping provider and when its label has been printed.

Example request header::

  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

Example request

curl -X PATCH \
  'https://api.shipping.montonio.com/stores/store-webhook' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoiOTZlNjhlZDEtMDkzOC00NTE0LWFkZDEtYmE1MGE0NmI3YWZkIiwiaWF0IjoxNjAzNzE1MjczLCJleHAiOjE2MDM3MTg4NzN9.LpSPYEtkRd5Ze4RZoeN8rRs6hzNP1cqw_Th8x4oRCXo'
  -d '{
    "tracking_webhook_url": "https://www.example.com/shipping-api-webhook"
  }'

URL

https://api.shipping.montonio.com/stores/store-webhook

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Body

Key	Required	Data type	Notes	Example Value
tracking_webhook_url	yes	string	The URL to send a webhook notification when a shipment is created or a label is printed	"https://www.example.com/shipping-api-webhook"

Receiving a webhook call

If a webhook URL has been registered with the API, it will send a POST request with relevant data to the URL whenever a shipment is created or a label is printed for it. The data is stored in a webhook_token query parameter which needs to be decoded using your secret key.

Validating the webhook token

The webhook_token that is included in the webhook query parameter needs to be validated. The token is signed with your Secret Key. On the code panel you can see examples of validating the token.

Show / Hide Parameters

Headers

Key	Type	Description
alg	string	Always set to HS256
typ	string	Always set to JWT

Payload

Key	Type	Description
message	string	A short message indicating the event that triggered the hook (currently shipment_created or label_created)
merchant_reference	string	The order reference number you provided when creating the shipment
shipment_uuid	string	The shipment’s UUID in Montonio.
shipment_status	string	Shipment status. registered_with_provider if shipment was created and successfully registered with the shipping provider. label_created when the label for the shipment has already been printed at least once.
tracking_numbers	array	An array containing one or more tracking code objects for the shipment (one for each parcel if multiparcel shipment), see below.

Payload: Tracking number

Key	Type	Description
code	string	The tracking code belonging to a parcel
link	string	The full URL with the tracking code to the shipping provider’s tracking page

Show / Hide Example Code

JavaScript

/**
 * We recommend using the jsonwebtoken package to verify
 * Json Web Tokens. You can install it with npm:
 * > npm install jsonwebtoken
 * More information can be found at
 * https://www.npmjs.com/package/jsonwebtoken
 */
const jwt = require('jsonwebtoken');

// fetched from the URL
const webhook_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXNzYWdlIjoic2hpcG1lbnRfY3JlYXRlZCIsIm1lcmNoYW50X3JlZmVyZW5jZSI6Ijk1Iiwic2hpcG1lbnRfdXVpZCI6ImZkZGI2MWJhLTA4YTMtNDRkOS04NWJiLWIxYjExMjVmNzM4OSIsInNoaXBtZW50X3N0YXR1cyI6InJlZ2lzdGVyZWRfd2l0aF9wcm92aWRlciIsInRyYWNraW5nX251bWJlcnMiOlt7ImNvZGUiOiIwNTYwNTYwMDI4MTk3NSIsImxpbmsiOiJodHRwczovL3RyYWNraW5nLmRwZC5kZS9zdGF0dXMvZW4vcGFyY2VsLzA1NjA1NjAwMjgxOTc1In0seyJjb2RlIjoiMDU2MDU2MDAyODE5NzYiLCJsaW5rIjoiaHR0cHM6Ly90cmFja2luZy5kcGQuZGUvc3RhdHVzL2VuL3BhcmNlbC8wNTYwNTYwMDI4MTk3NiJ9XSwiaWF0IjoxNjUxNDk5NTU5LCJleHAiOjE2NTE1MTM5NTl9.8JIAn-1nyTcZf2SgNvCDtOELRBdLZdTOk5-kQNk8Ubs';

const decoded = jwt.verify(webhook_token, 'merchant_secret_key');

if (decoded.message === 'shipment_created') {
    // shipment created and registered with provider
} else if (decoded.message === 'label_created') {
    // label printed for shipment
}

PHP

<?php
/**
 * We recommend using Firebase's php-jwt package to verify
 * Json Web Tokens. You can install it with composer:
 * > composer require firebase/php-jwt
 * More information can be found at
 * https://github.com/firebase/php-jwt
 */
use \Firebase\JWT\JWT;

// fetched from the URL
$webhook_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXNzYWdlIjoic2hpcG1lbnRfY3JlYXRlZCIsIm1lcmNoYW50X3JlZmVyZW5jZSI6Ijk1Iiwic2hpcG1lbnRfdXVpZCI6ImZkZGI2MWJhLTA4YTMtNDRkOS04NWJiLWIxYjExMjVmNzM4OSIsInNoaXBtZW50X3N0YXR1cyI6InJlZ2lzdGVyZWRfd2l0aF9wcm92aWRlciIsInRyYWNraW5nX251bWJlcnMiOlt7ImNvZGUiOiIwNTYwNTYwMDI4MTk3NSIsImxpbmsiOiJodHRwczovL3RyYWNraW5nLmRwZC5kZS9zdGF0dXMvZW4vcGFyY2VsLzA1NjA1NjAwMjgxOTc1In0seyJjb2RlIjoiMDU2MDU2MDAyODE5NzYiLCJsaW5rIjoiaHR0cHM6Ly90cmFja2luZy5kcGQuZGUvc3RhdHVzL2VuL3BhcmNlbC8wNTYwNTYwMDI4MTk3NiJ9XSwiaWF0IjoxNjUxNDk5NTU5LCJleHAiOjE2NTE1MTM5NTl9.8JIAn-1nyTcZf2SgNvCDtOELRBdLZdTOk5-kQNk8Ubs';

$decoded = Firebase\JWT\JWT::decode(
    $webhook_token,
    'merchant_secret_key',
    array('HS256')
);

if ($decoded->message === 'shipment_created') {
    // shipment created and registered with provider
} else if ($decoded->message === 'label_created') {
    // label printed for shipment
}

?>

Python

'''
We recommend using the PyJWT package to verify
Json Web Tokens. You can install it with pip:
> pip3 install PyJWT
More information can be found at
https://pyjwt.readthedocs.io/en/latest/
'''
import jwt

# fetched from the URL
webhook_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXNzYWdlIjoic2hpcG1lbnRfY3JlYXRlZCIsIm1lcmNoYW50X3JlZmVyZW5jZSI6Ijk1Iiwic2hpcG1lbnRfdXVpZCI6ImZkZGI2MWJhLTA4YTMtNDRkOS04NWJiLWIxYjExMjVmNzM4OSIsInNoaXBtZW50X3N0YXR1cyI6InJlZ2lzdGVyZWRfd2l0aF9wcm92aWRlciIsInRyYWNraW5nX251bWJlcnMiOlt7ImNvZGUiOiIwNTYwNTYwMDI4MTk3NSIsImxpbmsiOiJodHRwczovL3RyYWNraW5nLmRwZC5kZS9zdGF0dXMvZW4vcGFyY2VsLzA1NjA1NjAwMjgxOTc1In0seyJjb2RlIjoiMDU2MDU2MDAyODE5NzYiLCJsaW5rIjoiaHR0cHM6Ly90cmFja2luZy5kcGQuZGUvc3RhdHVzL2VuL3BhcmNlbC8wNTYwNTYwMDI4MTk3NiJ9XSwiaWF0IjoxNjUxNDk5NTU5LCJleHAiOjE2NTE1MTM5NTl9.8JIAn-1nyTcZf2SgNvCDtOELRBdLZdTOk5-kQNk8Ubs'

try:
    decoded = jwt.decode(
        webhook_token,
        'merchant_secret_key',
        algorithms=['HS256']
    )

except jwt.exceptions.InvalidSignatureError as identifier:
    pass # Token validation failed

if  (decoded['message'] == 'shipment_created'):
    pass # shipment created and registered with provider
elif (decoded['message'] == 'label_created'):
    pass # label printed for shipment

Head back to Montonio