GROperator

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
POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks
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"
}'
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
POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test
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"
EventSent whenStatus name in payload
shipment.createdA shipment was created (from the dashboard, an import or the API).Created
shipment.picked_upThe courier collected the shipment from the sender.PickedUp
shipment.out_for_deliveryThe shipment left for delivery with a courier.OutForDelivery
shipment.deliveredThe shipment was delivered (fully or partially).Delivered
shipment.cancelledThe shipment was cancelled.Cancelled
shipment.on_holdThe shipment is held in the warehouse.OnHoldWarehouse
shipment.lostThe shipment was declared lost.Lost
shipment.damagedThe shipment was declared damaged.Damaged
shipment.ndr_createdA delivery attempt failed (non-delivery report).DeliveryAttempted
shipment.rto_initiatedThe shipment started its way back to the sender.RTOInitiated
shipment.rto_received_at_warehouseThe returning shipment was received at the warehouse.RTOInitiated
shipment.rto_out_for_returnThe returning shipment is on its way to the sender.RTOInTransit
shipment.rto_refused_by_merchantThe merchant refused the returned shipment.RTOInTransit
shipment.returned_to_merchantThe 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" }:

JSON
{
  "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.

  1. Read the raw body before any JSON parsing. Re-serialising parsed JSON changes the bytes and breaks the check.
  2. Compute the HMAC with the secret.
  3. Compare with X-Signature in constant time.
  4. Reject the request with 401 if 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);

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 2xx quickly and is idempotent.
  • You tested it with POST .../test.