Skip to content

Webhooks

Contents 26 pages

We POST an event to your endpoint whenever freight moves. Add one at /portal/webhooks — you need to be your organization's owner or admin.

The URL must be https on port 443, with no credentials in it, and resolve to a public address. We check it again before every attempt. An organization can have five endpoints.

Webhooks are an optimization on top of the change feed, not a replacement. Events stays the source of truth, and it is how you recover anything a webhook missed.

Webhooks are for web app organizations. A Shopify store's key reads its events with GET /events, where an event's data carries dates, ids and codes only.

Verifying a request#

Every request carries a signature over the exact bytes we sent:

X-ShipEasy-Signature: t=1787745600,v1=3f9a…
X-ShipEasy-Event-Id: cm2k9e4v7…
X-ShipEasy-Delivery-Id: cm2k9w1n6…

v1 is HMAC-SHA256 of <t>.<raw request body>, keyed with your signing secret.

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE = 300; // seconds

function verify(secret, rawBody, header) {
	const parts = {};
	for (const part of (header ?? "").split(",")) {
		const eq = part.indexOf("=");
		if (eq > 0) parts[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
	}
	const t = Number(parts.t);
	if (!Number.isInteger(t) || !parts.v1) return false;
	// Freshness FIRST: a valid signature on an old body is still a replay.
	if (Math.abs(Date.now() / 1000 - t) > TOLERANCE) return false;
	const expected = createHmac("sha256", secret)
		.update(`${t}.`)
		.update(rawBody)
		.digest();
	const given = Buffer.from(parts.v1, "hex");
	return given.length === expected.length && timingSafeEqual(given, expected);
}

Three things people get wrong here, in the order they get them wrong:

  1. Sign the raw bytes, not a re-serialization. Parse the JSON after you verify. Re-encoding it changes key order or whitespace and every signature fails.
  2. Check the timestamp. Without it you have authenticity but no freshness, and a captured body works forever. We reject nothing on your behalf.
  3. Compare in constant time. timingSafeEqual or compare_digest, not ==.

In Express, give the webhook route express.raw({ type: "application/json" }) so req.body is the raw Buffer, and verify before you parse it.

Extra parts may appear in the header later (v2=…). Read the v1 you know and ignore the rest.

Answer 2xx first, work afterwards#

Any 2xx means delivered. Store the event, return, and do the real work out of band.

Anything else is a retry — including a 3xx, because we do not follow redirects. We retry after roughly 1 minute, 5, 15, 1 hour, then 6 hours: six attempts in all, the last about 7½ hours after the first. A URL that has come to resolve to a private address is not retried.

If your endpoint refuses us 20 times in a row we stop delivering to it entirely; fix it and press Send test event, and a success starts it again. While it is stopped nothing new is queued for it. Once it is back, what was queued goes out, with any events from the last 24 hours; read anything older from the events feed.

Requests time out after 10 seconds.

If your organization's API access is switched off, or the account is suspended, we send nothing meanwhile. Deliveries already queued wait rather than fail, and go out once access is back, together with any events from the last 24 hours you were owed meanwhile.

Deliveries are at-least-once#

Key on X-ShipEasy-Event-Id and ignore an id you have already stored. The id is stable across every retry and redelivery of the same event, so this is all the deduplication you need.

The body#

The event, with the shipment embedded as the API's own shipment object:

JSON
{
	"id": "cm2k9e4v7…",
	"object": "event",
	"type": "shipment.eta_changed",
	"created": "2026-08-26T12:00:00.000Z",
	"data": {
		"object": { "object": "shipment", "id": "cm2k8x7d2…", "status": "in_transit" },
		"shipment_id": "cm2k8x7d2…",
		"booking_id": null,
		"status": null,
		"previous_eta": "2026-09-01T00:00:00.000Z",
		"eta": "2026-09-04T00:00:00.000Z",
		"appointment_from": null,
		"appointment_to": null,
		"eta_source": "estimate"
	}
}

data.object is the shipment as GET /shipments lists it, as it stood when the event was queued; a retry resends the same bytes. It has no origin, destination or handling_units: fetch GET /shipments/{id} for those. The rest of data is the delta for this event type.

Bookings that never became freight#

A booking the bank challenged, the card refused, nobody finished in time, or the carrier would not take has no shipment. Its event names the booking instead: data.shipment_id is null, data.booking_id is set, and data.object is the booking as GET /bookings/{id} returns it, except that authenticate_url and refund are always null.

JSON
{
	"id": "cm2kc3f8a…",
	"object": "event",
	"type": "booking.declined",
	"created": "2026-10-21T15:00:00.000Z",
	"data": {
		"object": {
			"object": "booking",
			"id": "cm2k8t5c1…",
			"status": "declined",
			"decline_code": "insufficient_funds",
			"shipment_id": null,
			"next_step": "The card was declined. Nothing was charged. Try a different card."
		},
		"shipment_id": null,
		"booking_id": "cm2k8t5c1…",
		"status": null,
		"reference": "PCH-7KQ4M2X",
		"decline_code": "insufficient_funds"
	}
}

Each type is named for the booking status it reached, so a handler can branch on either. Each is sent at most once per booking. booking.requires_authentication carries no authenticate_url: the link is handed out once, in the POST /bookings reply, and is never stored where a redelivery could replay it. A booking.failed booking is with our team, who may still book it; if they do, booking.completed follows on the new shipment.

Event types#

Choose the ones you want, or leave them all unchecked to receive everything — including types we add later.

Type When data carries
shipment.status_changed our status OR the carrier's wording moves status.from / status.to, and status.carrier_from / status.carrier_to
shipment.eta_changed the carrier's estimated delivery or appointment window moves, appears or is withdrawn previous_eta, eta, appointment_from, appointment_to, eta_source (appointment, estimate, or null)
shipment.picked_up the carrier collected it picked_up_at
shipment.delivered it reached the consignee delivered_at
shipment.alert_opened the carrier flagged something; an exception or delay once we have reviewed it alert.code, alert.label, alert.category, alert.reason
shipment.alert_cleared the carrier stopped reporting one you were sent the same alert
shipment.tracking_updated a PRO or carrier tracking link was assigned, changed or removed pro_number, carrier_tracking_url
shipment.document_available a BOL or POD appeared kind (bol or pod)
shipment.delivery_overdue a full day after the promised delivery, with no arrival promised_for, promise_source, appointment_to
shipment.cancellation_confirmed the carrier, or our team, confirmed the cancellation status.from / status.to (cancelled)
booking.completed the carrier booking landed; the shipment exists reference, pro_number, carrier
booking.requires_authentication the cardholder's bank wants a person reference (the booking is data.object)
booking.declined the card was refused; nothing charged reference, decline_code
booking.expired nobody finished it in time; released reference
booking.failed paid, and the carrier booking did not land reference
ping only when you press Send test event message; data.object is null, and both id headers are test

A BOL is announced once, when it appears. For most bookings that is the moment of booking, right beside booking.completed; when the carrier returns it later, it is when we attach it. A re-signed link to the same document is not a new document, and neither is sent again.

Watch status.carrier_*. Our status has five values, so several carrier milestones collapse into in_transit — "Out for Delivery" among them. If you care about those, branch on status.carrier_to, which is the carrier's own word.

alert.category is the severity, and attribute is not a problem. A carrier alert can be exception, delay, progress, scheduling, paperwork or attribute. The last one is a standing fact about the freight — Insured, Oversized, Hazardous Material — and it stays on the shipment for its whole life. Treating a customer-visible alert as trouble marks every insured shipment broken. Only exception and delay mean something is wrong.

An exception or delay is reviewed before you hear of it. Our team checks each one the carrier raises, so its alert_opened arrives when we confirm it, which can be a while after the carrier raised it, together with the exception email. One we judge to be noise is never sent, and neither is its alert_cleared. A scheduling alert (an appointment request) is sent at once.

Events: you can also just read them#

GET/api/v1/eventsScope shipments:read
Shell
curl "https://app.shipeasyco.com/api/v1/events?updated_since=2026-08-26T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"

Requires shipments:read. Without updated_since it is newest first. Narrow it with type, shipment_id or booking_id.

With updated_since this is oldest-first and resumable from a cursor — which is exactly how you catch up after your endpoint was down. You do not need a replay request from us. The feed runs about ten seconds behind the clock, so that an event saved a moment after a later-stamped one still reaches you. Carry your high-water mark forward from created and nothing is skipped. See the settle window.

GET/api/v1/shipments/{shipmentId}/eventsScope shipments:read
Shell
curl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/events \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"

One shipment's timeline — the read a support conversation usually starts with. A booking that never became freight has no shipment to ask for; filter the feed by it instead, with GET /api/v1/events?booking_id=cm2k8t5c1….

Rotating and removing#

New secret replaces the signing secret immediately, with no overlap window: a signature is verified per request with no lookup, so honouring two secrets would mean sending two headers. Deploy the new one promptly. A delivery still being retried is signed with the new secret from its next attempt.

Remove stops delivery and drops anything queued. It cannot be undone — adding the endpoint again gives you a new secret.

The 20 most recent deliveries are listed under each endpoint at /portal/webhooks, each with its attempts, its last response code and latency, and its next retry.