Overview

• Webhooks (callbacks) are scheduled or event driven executions of code to send data from one application to another.
• An example of a webhook is a push notification from an email server to your phone.
• Starshipit can send webhook requests when we receive tracking updates from your courier for your orders. You can specify a notification endpoint URL where Starshipit will send these requests.

How it works

You can use the notification endpoint URL to receive our webhook data and trigger a certain event in your own application.
E.g. Send an order update email to your customer or update the order status in your database when 'OutForDelivery' tracking status is received.

The notification endpoint URL needs to be built to accept the POST request that returns HTTP 200 OK response and the URL can be set in Starshipit > Settings > Tracking & notifications.

Webhook JSON Data Definitions

order_number

carrier_name

carrier_service

shipment_date

tracking_number

tracking_status

last_updated_date

Tracking Statuses

• Printed
• Dispatched
• InTransit
• OutForDelivery
• Delivered
• PickupInStore
• AttemptedDelivery
• Exception
• AwaitingCollection
• Cancelled

Webhook POST Data Example

{
  order_number:5567476,
  carrier_name:Australia Post,
  carrier_service:7B05,
  shipment_date:2018-08-09T02:55:37.1446912Z,
  tracking_number:QQQ001737901000931501,
  tracking_status:Dispatched,
  last_updated_date:2018-08-09T02:56:07.3453198Z
}

(Optional) Securing Webhooks

We have recently added support to secure webhooks by providing a secret key. You can generate a secret key from this settings page or provide your own.

If a secret is specified, any webhooks received from Starshipit will include a x-starshipit-signature header containing a signature.

See the following examples for how this signature can be checked:

Javascript Example

// JavaScript: Validate webhook signature using the Web Crypto API
async function validateWebhook(payload, headerSignature, secret) {
const encoder = new TextEncoder();
const keyData = encoder.encode(secret);
const payloadData = encoder.encode(payload);

// Import the secret key for HMAC-SHA256
const cryptoKey = await crypto.subtle.importKey(
"raw",
keyData,
{ name: "HMAC", hash: "SHA-256" },
false,
["sign"]
);

// Compute the HMAC signature of the payload
const signatureBuffer = await crypto.subtle.sign("HMAC", cryptoKey, payloadData);
const signatureArray = Array.from(new Uint8Array(signatureBuffer));
const computedSignature = signatureArray.map(b => b.toString(16).padStart(2, '0')).join('');

return computedSignature === headerSignature;
}

// Example usage:
const payload = JSON.stringify({ order_number: "12345", tracking_number: "ABC123"
});
const headerSignature = "your_header_signature_here"; // Replace with actual header signature
const secret = "your_shared_secret_here"; // Replace with your shared secret

validateWebhook(payload, headerSignature, secret)
.then(isValid => {
console.log(isValid ? "Valid webhook signature!" : "Invalid webhook signature.");
});

Python Example

import hmac
import hashlib
import json

def validate_webhook(payload, header_signature, secret):
# Ensure payload is a JSON string. If payload is a dict, convert it.
if isinstance(payload, dict):
payload = json.dumps(payload, separators=(',', ':'))
# Compute HMAC-SHA256 signature
computed_signature = hmac.new(
secret.encode('utf-8'),
payload.encode('utf-8'),
hashlib.sha256
).hexdigest()
return computed_signature == header_signature

# Example usage:
payload = '{"order_number": "12345", "tracking_number": "ABC123"}'
header_signature = "your_header_signature_here" # Replace with actual header signature
secret = "your_shared_secret_here" # Replace with your shared secret

if validate_webhook(payload, header_signature, secret):
print("Valid webhook signature!")
else:
print("Invalid webhook signature.")