Skip to content
First DeliveryFirst DeliveryFirst Delivery API

Webhooks

Webhooks are outbound HTTP callbacks First Delivery sends to registered URLs when an order changes state. They are signals, not the source of truth; reconcile business-critical state with Get Order.

Authentication and scopes

Section titled “Authentication and scopes”
  • webhooks:read lists registrations.
  • webhooks:write creates, updates, or deletes registrations.

Quick start

Section titled “Quick start”
  1. Register a URL with POST /api/webhooks.
  2. Optionally set event_filter.
  3. Return 2xx within 5 seconds and process asynchronously.
  4. Branch on status_v3 and dedupe by order/event state.
  5. Reconcile terminal states with Get Order.

Delivery semantics

Section titled “Delivery semantics”
  • Method is POST with Content-Type: application/json and a 5-second timeout.
  • Failed or timed-out attempts are recorded but are not automatically retried.
  • Ordering is not guaranteed; consumers must tolerate duplicate and out-of-order events.
  • Headers in http_options.headers are sent on every call, encrypted at rest, and masked when listed.
  • A literal $ in the URL is replaced with the order’s external ID.
  • Same-status and very rapid events may be suppressed. Runner location is not streamed.
  • Source operators receive events; an active supplying fleet operator also receives applicable events.
  • Quotes do not emit webhooks.

Event model

Section titled “Event model”

Typical lifecycle: scheduled → en_route_pickup → arrived_pickup → en_route_dropoff → arrived_dropoff → completed. Alternate events include cancelled, reassign, Refunded, and opt-in ready_now.

status_v3 is the canonical lifecycle value. status is retained for legacy compatibility. Driver, location, ETA, proof-of-delivery, fee, cancellation, and DSP tracking fields are conditional. trackerLinkFleet and fleetName are present on new payloads but may be null.

Consumer practices

Section titled “Consumer practices”

Acknowledge quickly, enqueue durably, process idempotently, do not assume ordering, treat optional fields defensively, reconcile critical state by polling, keep custom receiver headers private and rotated, and alert on non-2xx responses, timeouts, queue lag, and stale-order reconciliation failures. Every delivery attempt is visible in Dispatch → Developer Settings → Webhooks.

Endpoints

Section titled “Endpoints”