Set up my webhooks

Step by step setup

Setup the webhook in your account

1. Ask for your webhook activation to your contact @ shiptify

2. Go to Settings

3. Go to Webhooks tile inside My Settings section

4. Click on + Add new URL

5. Select events to start receiving updates

Webhook Set Up inside your Shiptify account

Server Codes

For Webhook POSTs, Shiptify listens for the following codes from your server and reacts accordingly:

• If Shiptify receives a 200 (Success) code it will determine the webhook POST is successful and not retry.

• For any other code, Shiptify will retry POSTing according to the schedule below for Webhooks other than the delivery notification.

If your application is unable to process the webhook request but you do not return a 406 error code, Shiptify will retry (other than for delivery notification) during 24 hours at the following intervals before stop trying: 0 minutes, 30 minutes, 1 hour, 4 hours and 24 hours.

Securing Webhooks

To ensure the authenticity of event requests, Shiptify signs them and posts the signature along with other webhook parameters.

If you want to verify the requests, please ask your Shiptify account manager about it and follow the process here under.

The signature parameters are described in securing webhooks and the event-data parameters are the same as described in Event Structure

{
    "event_type": "create_shipment",
    "timestamp": 1643117545594,
    "signature": "string",
    "token": "string"
}

Parameter	Type	Description
timestamp	int	Number of seconds passed since January 1, 1970.
signature	string	String with hexadecimal digits generate by HMAC algorithm.
token	string	Randomly generated string with length 50.

To verify the webhook is originating from Shiptify you need to:

• Concatenate timestamp and token values.

• Encode the resulting string with the HMAC algorithm (using your Webhook Signing Key as a key and SHA256 digest mode).

• Compare the resulting hexdigest to the signature.

• Optionally, you can cache the token value locally and not honor any subsequent request with the same token. This will prevent replay attacks.

• Optionally, you can check if the timestamp is not too far from the current time.

Note: Due to potentially large size of posted data, Shiptify computes an authentication signature based on a limited set of HTTP headers.

Here’s a sample in Node.js

const crypto = require('crypto')

const verify = ({ signingKey, timestamp, token, signature }) => {
    const encodedToken = crypto
        .createHmac('sha256', signingKey)
        .update(timestamp.concat(token))
        .digest('hex')

    return (encodedToken === signature)
}

Shipment Modes

Mode Type	ID
air	1
sea	2
road	3
rail	4
express	5
groupage	6
courier	7
air-sea	8

Content Types

You can request an access to the Production Content Types library directly with your contact @ Shiptify.

Auto-test your webhook

When you think you have successfully set up your webhook, you can test it by yourself by creating a test shipment.

You can do so by switching to your shipper demo account. Switch to shipper account by clicking on the top bar icons for accounts.

Switching account Icon

The webhook will be triggered only if the shipment is confirmed. So you will have to confirm it by yourself either on shipper side (Auto Confirm) or on carrier side (Regular carrier confirmation).