Skip to Content

Developer / API Learning Center

Integrate shipping, tracking, labels, and rate quotes into your platform.

New Account Explore Our Services

Webhooks

Webhooks allow Jet Delivery to send shipment events to your system in real time (pickup, delivery, dispatch updates, etc.). This is the best way to keep your platform up to date without polling.

Recommended: Your webhook endpoint should respond quickly with 200 and process events asynchronously.

Setup

  • Create an HTTPS endpoint in your system to receive webhook deliveries.
  • Configure your endpoint URL (and selected event types) in your Jet Delivery account portal.
  • Log webhook deliveries and return 200 quickly. Jet records each delivery attempt for troubleshooting.
Tip: Start by logging the raw request body + headers for the first day of testing so you can validate event delivery and payload fields.

Delivery behavior

  • HTTP method: POST
  • Content-Type: application/json
  • Response: return 200 to acknowledge receipt
  • Retries: automatic retries are not currently guaranteed; do not rely on a failed delivery being resent

If you need strict idempotency, use an event ID (or track number + datetime + description) as a dedupe key in your system.

Security

  • Use HTTPS for your webhook endpoint.
  • Validate that the request body is valid JSON and matches your expected shape.
  • Do not trust inbound fields blindly—treat webhook content as untrusted input.
  • Use HMAC signing or a shared-secret header when configuring the endpoint in your account portal.
HMAC verification: Jet calculates an HMAC-SHA256 signature over the exact raw JSON request body, encodes it as lowercase hexadecimal, and sends it in the header name you configure. Calculate the same value with your HMAC secret and compare signatures using a constant-time comparison.

Basic authentication and a configurable shared-secret header are also supported. OAuth 2.0 client credentials should not be selected yet because token acquisition is not currently enabled for outbound deliveries.

Event types

Webhooks send event notifications when shipment status changes. Exact event types may vary by account configuration and service type.

Common events include: dispatch, picked up, in transit, delivered, and exception updates.
  • Dispatch updates: driver assigned / driver dispatched
  • Pickup: pickup completed / departed origin
  • Delivery: delivered / signature captured
  • Exceptions: cancellation / failed attempt / reschedule (if applicable)

The authoritative event list for your account appears in Settings > API Access & Webhooks when you create or edit an endpoint.

Payload (example shape)

{
  "event_type": "delivered",
  "record_id": "1234567",
  "status_code": "15",
  "status_description": "Delivered",
  "event_datetime": "2026-02-26T13:09:00-08:00",
  "reference": "PO-10045",
  "signature": "Alex Morgan",
  "record_url": "https://www.jetdelivery.com/smartship/tools/order/?idx=1234567"
}
Event-specific fields vary. Jet always adds record_id and record_url, and adds reference when the shipment has a customer reference. Use record_id as the shipment identifier.

Recommended handling

  • Verify your endpoint is reachable and returns 200.
  • Store the raw payload (at least during initial rollout).
  • Process the event asynchronously (queue/job worker) to avoid timeouts.
  • Implement dedupe (idempotency) in case the same event is delivered more than once.

Example (acknowledge quickly)

# Your endpoint should respond quickly:
HTTP/1.1 200 OK
Content-Type: application/json

{"ok": true}

Troubleshooting

  • No deliveries: endpoint URL incorrect, not publicly reachable, or events not selected.
  • Repeated events: upstream status sources may send the same event more than once; deduplicate before applying state changes.
  • Invalid JSON: log raw body and confirm your parser matches the payload shape.