Nitromule

Webhooks

Updated 2026-09-07

On this page

Webhooks push events to your HTTPS endpoint when orders and shipments change so you do not poll. Verify deliveries and respond with 2xx quickly.

Events

Event When
order.created Order created via API (or eligible creates)
order.updated Order fields / status change
shipment.created Label purchased
shipment.voided Label voided
tracking.updated Tracking update for a shipment you own

Register

Via API (GET/POST/DELETE /webhooks) — confirm schema in OpenAPI.

curl -sS "$NM_API/webhooks" \
 -H "Authorization: Bearer $NM_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://example.com/hooks/nitromule",
 "events": [
 "shipment.created",
 "shipment.voided",
 "tracking.updated"
 ]
 }'

Endpoint requirements

  • Public HTTPS URL
  • Respond 2xx within a few seconds
  • Process heavy work asynchronously
  • Tolerate duplicate deliveries (idempotent handlers)
  • Verify signing secret / signature headers from OpenAPI — reject mismatches

Test plan

  1. Register a webhook with a nm_test_ key against a tunnel (ngrok, Cloudflare Tunnel, etc.).
  2. Create an order and buy a test label.
  3. Confirm shipment.created arrives.
  4. Void and confirm shipment.voided.
  5. Promote the same handler to production with a nm_live_ key and production URL.

Ownership

You only receive events for resources owned by the API key. tracking.updated does not leak other merchants’ packages.

Tips

  • Log delivery ids for support
  • Pair with quickstart label lifecycle scripts
  • See test mode before going live

Related articles