Webhooks
Webhooks let LastMile call your server when something happens to a shipment, so you do not have to poll. Use them to keep your own order status up to date and to notify customers.
Scope: webhooks:manage. A subscription belongs to one merchant and receives that merchant's shipment events.
POST /merchants/{merchantId}/webhooks:
| Field | Details |
|---|---|
url |
Required. A public https address that receives the events. Local and private addresses are refused (security.unsafe_webhook_target_url, integrations.invalid_target_url) |
events |
Required, at least one. Event types from the table below, or the wildcards shipment.* (all shipment events) and * (everything) |
description |
Optional text to recognise the subscription, up to 200 characters |
curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"url": "https://shop.example.com/hooks/lastmile",
"events": [
"shipment.created",
"shipment.out_for_delivery",
"shipment.delivered"
],
"description": "Order system"
}'const response = await fetch("https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"url": "https://shop.example.com/hooks/lastmile",
"events": [
"shipment.created",
"shipment.out_for_delivery",
"shipment.delivered"
],
"description": "Order system"
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://shop.example.com/hooks/lastmile',
'events' => [
'shipment.created',
'shipment.out_for_delivery',
'shipment.delivered',
],
'description' => 'Order system',
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"url": "https://shop.example.com/hooks/lastmile",
"events": [
"shipment.created",
"shipment.out_for_delivery",
"shipment.delivered",
],
"description": "Order system",
},
timeout=30,
)
print(response.status_code, response.json()){
"id": "c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11",
"merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"url": "https://shop.example.com/hooks/lastmile",
"events": [
"shipment.created",
"shipment.out_for_delivery",
"shipment.delivered"
],
"description": "Order system",
"isActive": true,
"createdAt": "2026-01-15T09:00:00Z",
"secret": "5f1c0a7e9d3b..."
}The response contains the signing secret. It is shown once, here: store it as a secret on your server. To get a new one, rotate it with POST /merchants/{merchantId}/webhooks/{id}/rotate-secret; the old secret stops working immediately.
| Operation | What it does |
|---|---|
GET /merchants/{merchantId}/webhooks |
Lists the subscriptions of the merchant (without secrets) |
POST /merchants/{merchantId}/webhooks/{id}/test |
Queues a signed ping delivery to the URL, like a real event. Only active subscriptions can be tested |
POST /merchants/{merchantId}/webhooks/{id}/rotate-secret |
Returns a new secret, shown once |
DELETE /merchants/{merchantId}/webhooks/{id} |
Deletes the subscription. Past delivery logs are kept |
GET /webhooks/events |
The live event catalogue with descriptions and example payloads |
curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET"const response = await fetch("https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.json())| Event | Sent when | Status name in payload |
|---|---|---|
shipment.created | A shipment was created (from the dashboard, an import or the API). | Created |
shipment.picked_up | The courier collected the shipment from the sender. | PickedUp |
shipment.out_for_delivery | The shipment left for delivery with a courier. | OutForDelivery |
shipment.delivered | The shipment was delivered (fully or partially). | Delivered |
shipment.cancelled | The shipment was cancelled. | Cancelled |
shipment.on_hold | The shipment is held in the warehouse. | OnHoldWarehouse |
shipment.lost | The shipment was declared lost. | Lost |
shipment.damaged | The shipment was declared damaged. | Damaged |
shipment.ndr_created | A delivery attempt failed (non-delivery report). | DeliveryAttempted |
shipment.rto_initiated | The shipment started its way back to the sender. | RTOInitiated |
shipment.rto_received_at_warehouse | The returning shipment was received at the warehouse. | RTOInitiated |
shipment.rto_out_for_return | The returning shipment is on its way to the sender. | RTOInTransit |
shipment.rto_refused_by_merchant | The merchant refused the returned shipment. | RTOInTransit |
shipment.returned_to_merchant | The shipment was handed back to the merchant. | ReturnedToSender |
ping is sent only by the test endpoint and cannot be subscribed to. The catalogue is also served live by GET /webhooks/events.
Every delivery is a POST to your URL with a JSON body of the form { "event", "occurredAt", "data" }:
{
"event": "shipment.delivered",
"occurredAt": "2026-01-15T09:30:00Z",
"data": {
"trackingNumber": "AWB-RUH-000123",
"statusCode": 4040,
"statusName": "Delivered",
"trackUrl": "https://tracking.example.com/track/AWB-RUH-000123",
"awbUrl": "https://tracking.example.com/awb/AWB-RUH-000123",
"rtoTrackingNumber": null
}
}| Field | Meaning |
|---|---|
event |
The event type |
occurredAt |
When it happened, ISO 8601 UTC |
data.trackingNumber |
The shipment. Fetch GET /shipments/{trackingNumber} if you need more |
data.statusCode, data.statusName |
The status that caused the event (the enum name, such as Delivered) |
data.trackUrl, data.awbUrl |
Links to the public tracking page and the label |
data.rtoTrackingNumber |
The tracking number of the return shipment, when there is one; otherwise null |
The request carries these headers:
| Header | Value |
|---|---|
X-Event-Type |
The event type, repeated from the body |
X-Signature |
The signature, lowercase hexadecimal |
X-Webhook-Signature |
The same value as X-Signature |
The signature is hex(HMAC_SHA256(secret, rawBody)): the lowercase hexadecimal HMAC-SHA256 of the raw request body (the exact bytes received), keyed with the subscription secret. Always verify it before you trust a delivery.
- Read the raw body before any JSON parsing. Re-serialising parsed JSON changes the bytes and breaks the check.
- Compute the HMAC with the secret.
- Compare with
X-Signaturein constant time. - Reject the request with
401if it does not match.
// Node.js + Express. The webhook secret comes from the environment.
import crypto from "node:crypto";
import express from "express";
const app = express();
// Keep the raw bytes: the signature is computed over them, not over parsed JSON.
app.post("/hooks/lastmile", express.raw({ type: "application/json" }), (req, res) => {
const received = String(req.get("X-Signature") ?? "");
const expected = crypto
.createHmac("sha256", process.env.LASTMILE_WEBHOOK_SECRET)
.update(req.body) // a Buffer
.digest("hex");
const a = Buffer.from(received);
const b = Buffer.from(expected);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
// Store the event, answer quickly, work later.
console.log(event.event, event.data.trackingNumber, event.data.statusName);
res.sendStatus(200);
});
app.listen(3000);<?php
// The webhook secret comes from the environment.
$secret = getenv('LASTMILE_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input'); // the exact bytes received
$received = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $rawBody, $secret); // lowercase hex
if (!hash_equals($expected, $received)) { // constant-time comparison
http_response_code(401);
exit;
}
$event = json_decode($rawBody, true);
// Store the event, answer quickly, work later.
error_log($event['event'] . ' ' . $event['data']['trackingNumber']);
http_response_code(200);# Flask. The webhook secret comes from the environment.
import hashlib
import hmac
import os
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["LASTMILE_WEBHOOK_SECRET"].encode()
@app.post("/hooks/lastmile")
def lastmile_hook():
raw = request.get_data() # the exact bytes received
received = request.headers.get("X-Signature", "")
expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest() # lowercase hex
if not hmac.compare_digest(expected, received): # constant-time comparison
abort(401)
event = request.get_json(force=True)
# Store the event, answer quickly, work later.
print(event["event"], event["data"]["trackingNumber"])
return "", 200// ASP.NET Core minimal API. The webhook secret comes from configuration.
using System.Security.Cryptography;
using System.Text;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var secret = Encoding.UTF8.GetBytes(app.Configuration["LastMile:WebhookSecret"]!);
app.MapPost("/hooks/lastmile", async (HttpRequest request) =>
{
// Read the raw bytes: the signature is computed over them, not over parsed JSON.
using var buffer = new MemoryStream();
await request.Body.CopyToAsync(buffer);
var raw = buffer.ToArray();
var received = request.Headers["X-Signature"].ToString();
var expected = Convert.ToHexString(HMACSHA256.HashData(secret, raw)).ToLowerInvariant();
var a = Encoding.ASCII.GetBytes(received);
var b = Encoding.ASCII.GetBytes(expected);
if (a.Length != b.Length || !CryptographicOperations.FixedTimeEquals(a, b))
return Results.Unauthorized();
var json = System.Text.Json.JsonDocument.Parse(raw);
// Store the event, answer quickly, work later.
Console.WriteLine(json.RootElement.GetProperty("event").GetString());
return Results.Ok();
});
app.Run();Answer with any 2xx status as soon as you have stored the event, and do the slow work afterwards. Any other status, a timeout or a connection error counts as a failure and the delivery is retried after 1, 5 and 15 minutes. After that it is not sent again, so if your endpoint was down for long, reconcile with GET /shipments.
Because of retries and the network, plan for:
- Duplicates. The same event can arrive more than once. Make your handler idempotent, for example by remembering
event+data.trackingNumber+occurredAt. - Out-of-order delivery. Use
occurredAt, or fetch the shipment, rather than assuming the last event received is the newest. - Replays. The signature covers the body, which includes
occurredAt. If you want to refuse very old deliveries, compare it with your clock.
- The URL is public
https. - The secret is stored on the server and never logged.
- The signature is checked on the raw body in constant time.
- The handler answers
2xxquickly and is idempotent. - You tested it with
POST .../test.