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)
}