FleetBridge Order Source Integration
Everything an external Order Source engineering team needs to integrate with FleetBridge, in one offline-usable, self-contained page — authentication, order lifecycle, webhooks, signature verification, idempotency, errors, and certification.
Overview
API major: v1 Contract revision: 1.1.0 Audience: engineering teams at POS systems, restaurant platforms, e-commerce systems, ordering applications, marketplaces, and ERP/order-management systems that create delivery orders through FleetBridge (an "Order Source").
This document describes the public Order Source API as it actually behaves. Every field name, header, status code, and behavior below comes straight from the running FleetBridge implementation, not a design doc someone wrote before the code existed. If something genuinely isn't built yet (a fixed per-key rate limit, for instance), we say so plainly instead of pretending it's there.
1. Integration model
Order Source ──HTTP request───► FleetBridge Order API
Order Source ◄──HTTPS webhook── FleetBridge (delivery status / tracking events)FleetBridge sits between your system and one or more Delivery Providers. You never talk to a Delivery Provider directly, you never hold its credentials, and you never see its webhook format. Here's the flow:
- Create an order with FleetBridge.
- FleetBridge resolves a branch and dispatches a Delivery Provider, failing over to another one automatically if needed (before pickup only), and manages the delivery from there.
- FleetBridge sends you webhooks as the delivery progresses.
- You update or cancel the order through FleetBridge, not through the Delivery Provider.
- You always correlate on the identifiers FleetBridge gives you back. Not on the identity of whichever Delivery Provider happens to be handling the order at a given moment — that can change.
A few things this API deliberately doesn't do. There's no quotes or pricing endpoint; FleetBridge doesn't calculate delivery pricing or shop it across providers. There's no items[] concept anywhere in the contract, because FleetBridge orchestrates the delivery, not what's inside the order. And PaymentMethod is just order metadata passed through to the Delivery Provider — FleetBridge never settles or reconciles COD funds.
2. Authentication
2.1 Header
Every request is authenticated with a single header:
X-Api-Key: key_<64 lowercase hex characters>The header must be present exactly once, with a non-empty value. There's no Authorization: Bearer scheme for Order Source calls — that one's reserved for FleetBridge's own dashboard users.
2.2 Key format
A raw key is always key_ followed by 64 lowercase hexadecimal characters (68 characters total), for example:
key_9f2c1a7b3e5d8046a1c2b3d4e5f60718293a4b5c6d7e8f9012345678abcdef0FleetBridge generates the key and shows it to you exactly once, at creation time, in the tenant dashboard. It can't be redisplayed after that — FleetBridge only keeps a short, non-secret prefix (the first 12 characters, e.g. key_9f2c1a7b) for identification purposes. Lose it and it's gone for good; issue a new one and revoke the old one (Section 2.4).
There's no separate test/sandbox key format. A key authenticates against whatever FleetBridge environment (Base URL) it was issued for — see Section 20. Don't look for a _test_ / _live_ naming convention in the key itself, because there isn't one.
2.3 What the key identifies
A key belongs to exactly one Order Source inside exactly one Tenant. You never send a tenant ID or Order Source ID anywhere in the request — FleetBridge resolves both from the key itself. Your externalOrderId only needs to be unique within your Order Source, not across the whole tenant. A different Order Source under the same tenant can reuse the same externalOrderId for a completely unrelated order and FleetBridge keeps them apart without any extra effort on your part.
Every order, cancellation, update, and read you perform is scoped to what your own Order Source created. Try to read or modify an order that belongs to a different Order Source, even one under the same tenant, and you'll get 404 ORDER_NOT_FOUND — FleetBridge won't confirm or deny that such an order exists for someone else.
2.4 Rotation and revocation
Unlike webhook secrets (Section 9.10, which support rotation with an overlap window), there's no in-place "rotate" for an Order Source API key. To rotate one without downtime:
- Ask FleetBridge (through your tenant's dashboard user) to issue a new key for your Order Source. Multiple keys can be active for the same Order Source at once for exactly this reason.
- Deploy the new key to your systems.
- Ask FleetBridge to revoke the old key once you've confirmed the new one is working.
A revoked or expired key fails authentication immediately (Section 2.5). Both creation and revocation get recorded in FleetBridge's audit log.
2.5 Authentication failures
Two different failure layers here, with two different response shapes. Getting this distinction right matters for building correct error handling.
(a) The key itself is missing, malformed, unknown, revoked, or expired. This fails inside FleetBridge's authentication layer before your request ever reaches business logic. You get back:
HTTP/1.1 401 Unauthorizedwith an empty body — not a JSON error object. Don't try to parse one from a 401 here.
(b) The key is valid, but your Order Source or Tenant can't currently accept orders (disabled Order Source, suspended tenant). This is a business-rule rejection that happens *after* authentication succeeds, so it comes back through FleetBridge's standard error envelope (Section 16):
{
"status": 403,
"title": "Forbidden",
"detail": "This order source is disabled.",
"errorCode": "ORDER_SOURCE_DISABLED",
"correlationId": "0HNOOIIC1J8FA:00000001"
}| errorCode | HTTP status | Meaning |
|---|---|---|
TENANT_SUSPENDED | 403 | The tenant is not currently accepting new orders. |
ORDER_SOURCE_DISABLED | 403 | Your Order Source has been deactivated. |
INVALID_API_KEY | 403 | The authenticated caller is not a valid Order Source context for this operation (should not occur in normal use of a correctly issued key). |
2.6 What not to log
Never log the raw X-Api-Key header value, the raw webhook signing secret (Section 9), or full request bodies that carry customer phone numbers and addresses into whatever log retention policy you run. If you need to identify which credential made a call, log the key prefix (first 12 characters) instead — that part isn't sensitive.
3. Base URL and environments
We don't publish one fixed public hostname in this document, because your Base URL gets issued during onboarding and activation and is specific to your deployment. You'll receive:
- A staging Base URL and staging API key during development/certification.
- A production Base URL and production API key at activation.
Every example here uses the placeholder:
https://<fleetbridge-host>Swap in the actual Base URL you were given. The paths themselves (/api/v1/orders, etc.) are real and literal — only the host is a stand-in.
All endpoints are versioned under /api/v1. Section 21 covers the versioning and backward-compatibility policy if you want the details now.
4. Quick start
- Get your
X-Api-Keyand Base URL from FleetBridge during onboarding. - Register a webhook callback URL and grab your webhook signing secret (Section 9) — you'll want this before relying on lifecycle updates, though it's not required just to create a test order.
- Create an order (Section 7). Store the
platformOrderIdyou get back. - Poll
GET /api/v1/orders/{platformOrderId}/statusonce, or just wait for your first webhook, to watch the order move pastPendingRouting. - Implement webhook signature verification (Section 10) so you can actually trust the events you're receiving.
- Wire up Update and Cancel (Sections 11–12) for whichever parts of your own order lifecycle need them.
- Reconcile: if you're ever unsure whether a Create request actually went through (timeout, no response), replay the exact same request with the same
Idempotency-Key. Read Section 13 before you build any retry logic — the behavior here isn't what you'd guess.
First request, end to end
curl -X POST "https://<fleetbridge-host>/api/v1/orders" \
-H "X-Api-Key: key_9f2c1a7b3e5d8046a1c2b3d4e5f60718293a4b5c6d7e8f9012345678abcdef0" \
-H "Idempotency-Key: order-1001-create-1" \
-H "Content-Type: application/json" \
-d '{
"externalOrderId": "ORD-1001",
"branchId": null,
"externalBranchId": "MAIN-BRANCH",
"deliveryProviderCode": null,
"scheduledDeliveryAt": null,
"pickup": {
"address": "Ramallah Branch, Al-Manara St.",
"lat": 31.9021,
"lng": 35.2034
},
"dropoff": {
"customerName": "Ahmed Khalil",
"customerPhone": "+970590000000",
"customerEmail": null,
"address": "Al-Tireh, Ramallah",
"lat": 31.9102,
"lng": 35.2111
},
"payment": {
"method": "Cash",
"methodRaw": "cash_on_delivery",
"amount": 85.00,
"deliveryFee": 10.00,
"currency": "ILS"
},
"preparationTimeMinutes": 15,
"notes": "Call before arrival"
}'Response:
HTTP/1.1 201 Created
Location: /api/v1/orders/6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c
Content-Type: application/json{
"platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
"externalOrderId": "ORD-1001",
"externalOrderNumber": "ORD-1001",
"status": "PendingRouting",
"branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"routingMode": "PriorityFailover",
"createdAt": "2026-09-22T13:00:00Z"
}Store platformOrderId. Every subsequent call — Update, Cancel, GetById, GetStatus, GetTracking, GetTrackingHistory — uses it as a path parameter. externalOrderId comes back unchanged too, and you can use it to look the order up later (Section 12.4), scoped to your own Order Source. externalOrderNumber echoes your display number, or externalOrderId when you didn't send one (Section 7.1).
5. Every endpoint — summary
All paths are relative to your Base URL. All are under /api/v1.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/orders | Create an order |
| PATCH | /api/v1/orders/{platformOrderId} | Update mutable order business data |
| GET | /api/v1/orders/{platformOrderId} | Get full order detail |
| GET | /api/v1/orders/by-external-id/{externalOrderId} | Look up an order by your own reference |
| GET | /api/v1/orders/{platformOrderId}/status | Get current order + delivery status |
| GET | /api/v1/orders/{platformOrderId}/tracking | Get current driver/tracking snapshot |
| GET | /api/v1/orders/{platformOrderId}/tracking-history | Get the full tracking event timeline |
| POST | /api/v1/orders/{platformOrderId}/cancel | Cancel an order |
| POST | /api/v1/webhooks/test | Send a test webhook to your own registered endpoint |
All nine of these, webhook test included, require the X-Api-Key header (Section 2) and operate only on orders (or webhook endpoints) belonging to your own Order Source.
A few endpoints exist on this API but aren't available to an Order Source key — listed here just so you don't go looking for them: order search/listing, manual provider dispatch, return resolution, webhook endpoint management (create/rotate/subscribe), and Order Source or API key management. Those need a FleetBridge dashboard user session, so they're out of scope for this document.
6. Common conventions
- Request and response bodies are
application/json, fields incamelCase. - Enum values are always JSON strings (
"Cash", not0). An unrecognized enum string gets rejected as a validation error — it won't silently coerce to something else. - Any timestamp you send (
scheduledDeliveryAt) needs ISO 8601 with an explicit UTC offset (2026-09-01T18:30:00+03:00or...Z). Leave the offset off and it's rejected. Everything FleetBridge sends back is UTC, suffixedZ. - GUIDs (
platformOrderId,branchId, etc.) are lowercase, hyphenated UUID strings. - Unknown or extra JSON properties in a request get silently ignored, not rejected. Don't rely on that to smuggle data through — it's just how the underlying JSON binding happens to work.
7. Create Order
POST /api/v1/ordersOptional header: Idempotency-Key (Section 13). We'd strongly recommend sending it on every Create call — without it, a network-level retry looks identical to a second, separate order.
7.1 Request fields
| Field | Type | Required | Notes |
|---|---|---|---|
externalOrderId | string, ≤200 chars | Yes | Your own technical order identifier: the correlation, lookup, and de-dup key. Unique within your Order Source (Section 2.3). |
externalOrderNumber | string, ≤200 chars | No | Your human-readable order number (for example the number printed on the receipt). Shown to operators and sent to the Delivery Provider as its visible order reference. Display only: not unique, never used for correlation, lookup, de-duplication, or idempotency. Omitted or blank means FleetBridge uses externalOrderId. Set at create only. |
branchId | GUID | No | FleetBridge branch ID, if known. See Section 19 for resolution priority. |
externalBranchId | string | No | Your own branch/store code, if you don't track FleetBridge branch GUIDs. |
deliveryProviderCode | string | No | Request a specific Delivery Provider by code. See Section 15. |
scheduledDeliveryAt | ISO 8601 datetime w/ offset | No | Omit or null for an immediate (ASAP) order. See Section 14. |
pickup.address | string, ≤500 chars | Yes | Free-text pickup address (display/reference only — resolution uses coordinates/branch). |
pickup.lat | number | Yes | −90..90. |
pickup.lng | number | Yes | −180..180. |
dropoff.customerName | string, ≤200 chars | Yes | |
dropoff.customerPhone | string, ≤50 chars | Yes | |
dropoff.customerEmail | string, ≤320 chars | No | |
dropoff.address | string, ≤500 chars | Yes | |
dropoff.lat | number | Yes | −90..90. |
dropoff.lng | number | Yes | −180..180. |
payment.method | enum | Yes | One of Cash, Card, Online, Wallet, Other. See Section 17. |
payment.methodRaw | string, ≤100 chars | No | Your own original payment-method label, preserved alongside the normalized method. |
payment.amount | decimal | Yes | ≥0, at most 2 decimal places, at most 9,999,999,999.99. The order total. |
payment.deliveryFee | decimal | No | Same range/precision rules as amount. Informational only — never used in routing or provider selection. |
payment.currency | string, exactly ≤3 chars | Yes | e.g. ILS, USD. Normalized to uppercase. |
preparationTimeMinutes | integer | Yes | ≥0. No enforced upper bound. |
notes | string, ≤2000 chars | No |
One gotcha: if a required value-type field (lat, lng, amount, preparationTimeMinutes, payment.method) is missing from the JSON entirely, FleetBridge treats that exactly like an explicit required-and-missing field — it gets rejected, not quietly defaulted to zero. Send these explicitly, every time.
7.2 Minimal valid Create
{
"externalOrderId": "ORD-2002",
"externalBranchId": "MAIN-BRANCH",
"pickup": { "address": "Main Branch", "lat": 31.9021, "lng": 35.2034 },
"dropoff": {
"customerName": "Sara Ahmad",
"customerPhone": "+970599111222",
"address": "Al-Bireh",
"lat": 31.9075,
"lng": 35.2160
},
"payment": { "method": "Cash", "amount": 42.5, "currency": "ILS" },
"preparationTimeMinutes": 10
}7.3 Full Create (every optional field populated)
{
"externalOrderId": "ORD-2003",
"externalOrderNumber": "1042",
"branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"externalBranchId": null,
"deliveryProviderCode": "cervo",
"scheduledDeliveryAt": "2026-09-22T18:30:00+03:00",
"pickup": { "address": "Downtown Branch", "lat": 31.9021, "lng": 35.2034 },
"dropoff": {
"customerName": "Ahmed Khalil",
"customerPhone": "+970590000000",
"customerEmail": "ahmed@example.com",
"address": "Al-Tireh, Ramallah, Building 12",
"lat": 31.9102,
"lng": 35.2111
},
"payment": {
"method": "Card",
"methodRaw": "visa_online",
"amount": 120.00,
"deliveryFee": 12.00,
"currency": "ILS"
},
"preparationTimeMinutes": 20,
"notes": "Leave at the door, ring the bell twice"
}7.4 Response — 201 Created
{
"platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
"externalOrderId": "ORD-2003",
"externalOrderNumber": "1042",
"status": "Scheduled",
"branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"routingMode": "PriorityFailover",
"createdAt": "2026-09-22T13:05:00Z"
}The Location header comes back set to /api/v1/orders/{platformOrderId}. status is the order's first computed status: Scheduled if scheduledDeliveryAt was in the future, otherwise PendingRouting (Section 14). routingMode (DefaultOnly | ManualProvider | PriorityFailover | BroadcastToAll) comes from your tenant/branch configuration — it's not something you ask for per order. A deliveryProviderCode override (Section 15) changes which provider gets targeted, not the routing mode itself.
7.5 Errors specific to Create
| errorCode | Status | Cause |
|---|---|---|
BRANCH_NOT_FOUND | 404 | branchId/externalBranchId didn't resolve to an active branch, and no active branch matches the pickup coordinates either. |
INVALID_PICKUP_LOCATION | 400 | pickup.lat/pickup.lng out of range. |
INVALID_DROPOFF_LOCATION | 400 | dropoff.lat/dropoff.lng out of range. |
INVALID_AMOUNT | 400 | payment.amount or payment.deliveryFee negative. |
STRUCTURAL_LIMIT_EXCEEDED | 400 | A string field exceeded its max length, or an amount had more than 2 decimal places / exceeded the numeric cap. |
INVALID_PREPARATION_TIME | 400 | preparationTimeMinutes negative. |
INVALID_PAYMENT_METHOD | 400 | payment.method was not a recognized enum value. |
INVALID_SCHEDULED_TIME | 400 | scheduledDeliveryAt less than the minimum lead time in the future. See Section 14. |
PROVIDER_NOT_ENABLED | 400 | deliveryProviderCode unknown or not enabled for your tenant. |
MANUAL_OVERRIDE_NOT_ALLOWED | 400 | deliveryProviderCode supplied but manual provider selection is not permitted for this branch/tenant, or the requested provider isn't eligible right now. |
TENANT_SUSPENDED / ORDER_SOURCE_DISABLED | 403 | See Section 2.5. |
RATE_LIMIT_EXCEEDED | 429 | See Section 22. |
8. Order status, delivery status, and tracking
8.1 Two lifecycles, not one
FleetBridge keeps order status (your business view) and delivery status (the physical delivery view) separate. They're related, but not the same thing, and you should show/store both.
OrderStatus— the field you see asstatus/orderStatus— is your order's business lifecycle. FleetBridge derives it automatically from the order's attempts and shipment; you never set it directly. It moves in response to routing, provider events, cancellation, and operator actions.UnifiedDeliveryStatus— nested asdelivery.status/delivery.unifiedStatus— is the physical delivery, once one exists. It staysnull/absent until a Delivery Provider has actually been sent the order.
8.2 OrderStatus values
| Value | Meaning | Terminal? | Can you still Update/Cancel? |
|---|---|---|---|
Created | Momentary internal state immediately before the order is first persisted. You will never observe this value from any GET call — by the time an order is readable, it has already moved to Scheduled or PendingRouting. | No | — |
Scheduled | scheduledDeliveryAt is in the future; dispatch has not started. | No | Yes |
PendingRouting | Waiting for the routing engine to select/dispatch a provider. | No | Yes |
Dispatching | One or more delivery attempts are in flight — sent, awaiting acceptance, or failing over to the next provider. | No | Update yes; Cancel yes (immediate, platform-side). |
InDelivery | A Delivery Provider has accepted and the delivery is actively progressing (accepted through on-the-way). | No | Update yes; Cancel only if the provider supports cancellation at the current stage (Section 12). |
CancellationRequested | You (or an operator) requested cancellation; FleetBridge is waiting for the Delivery Provider to confirm. | No | A repeat Cancel call is safe (Section 12.3). |
ReturnInProgress | The delivery failed after pickup; a return-to-branch flow is active. See Section 18. | No | Read-only from your side; no self-service action. |
Delivered | Final: delivered to the customer. | Yes | No — 409 ORDER_ALREADY_FINAL. |
Cancelled | Final: cancellation confirmed. | Yes | No. |
Failed | Final: the delivery failed terminally, including "returned to origin" outcomes. | Yes | No. |
NoProviderAvailable | Held: every eligible provider was exhausted during automatic routing; a FleetBridge operator must intervene. | No | Update yes; Cancel yes. |
ManualReviewRequired | Held: a failure needs operator attention (failed cancellation, failed return, correlation problem). | No | Update yes; Cancel yes. |
Only Delivered, Cancelled, and Failed are truly final. The two "held" statuses (NoProviderAvailable, ManualReviewRequired) can resume automatically once a FleetBridge operator steps in, so don't treat them as final in your own state machine — and keep expecting webhooks for orders sitting in either state.
8.3 UnifiedDeliveryStatus values (the delivery.status field)
| Value | Meaning |
|---|---|
SentToProvider | Sent to a Delivery Provider, awaiting acceptance. |
ProviderAccepted | The Delivery Provider accepted the delivery. |
DriverAssigned | A driver has been assigned. |
ArrivedAtPickup | The driver has arrived at the branch. |
PickedUp | The driver has collected the order. |
OnTheWay | The order is en route to the customer. |
Delivered | Final: delivered. |
Cancelled | Final: cancelled. |
Failed | Final: failed (not a return case). |
ReturnRequested | Post-pickup failure; a return has been initiated. |
ReturningToOrigin | Goods are on the way back to the branch. |
ReturnedToOrigin | Final: goods are back at the branch (order-level status becomes Failed). |
ReturnFailed | The return itself could not be completed; requires operator resolution (order-level status becomes ManualReviewRequired). |
8.4 Lifecycle diagram
┌───────────┐
│ Scheduled │ (only if scheduledDeliveryAt is in the future)
└─────┬─────┘
│ dispatch time reached
▼
┌────────────────┐ ┌────────────────┐ ┌─────────────┐ ┌────────────┐
│ PendingRouting │───►│ Dispatching │───►│ InDelivery │───►│ Delivered │ (final)
└────────────────┘ │ (attempts/ │ │ (accepted → │ └────────────┘
│ failover) │ │ on the way)│
└───────┬────────┘ └──────┬──────┘
│ │
all providers exhausted failure after pickup
│ │
▼ ▼
┌────────────────────┐ ┌──────────────────┐
│ NoProviderAvailable │ │ ReturnInProgress │
│ (held) │ └────────┬─────────┘
└─────────────────────┘ │
▼
┌────────────┐
│ Failed │ (final; includes
└────────────┘ "returned to origin")
Cancellation, from any non-final status, at any point above:
Dispatching/PendingRouting/Scheduled → Cancelled directly (platform-side)
InDelivery (before pickup, if supported) → CancellationRequested → Cancelled
InDelivery (after pickup, if supported) → CancellationRequested → Cancelled
Any unexpected failure needing a human → ManualReviewRequired (held)Treat this as an orientation aid, not the literal implementation. OrderStatus gets recomputed from scratch on every relevant event — it's not a fixed adjacency list you could hard-code — so the exact transitions you see depend on your tenant's routing configuration and whatever the Delivery Provider itself supports. For what's actually authoritative, go back to the table in 8.2 (terminal vs. held vs. active).
8.5 Get order status
GET /api/v1/orders/{platformOrderId}/status{
"platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
"orderStatus": "InDelivery",
"delivery": {
"shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"platformReference": "att_18c9a4f2b3c1a2b3c4d5e6f708192a3b",
"deliveryProviderId": "5e9ca8a5-0c61-4312-ba14-cf9546aea68a",
"providerCode": "cervo",
"unifiedStatus": "DriverAssigned",
"slaStatus": "OnTrack"
}
}delivery stays null until a Delivery Provider has actually been sent the order — so while orderStatus is still Scheduled or PendingRouting, expect it to be empty. slaStatus is one of OnTrack, AtRisk, Breached, CompletedWithinSla, CompletedBreached, NotApplicable.
GET /api/v1/orders/{platformOrderId} (full detail) gives you everything above plus your original business fields: customer, addresses, payment, notes, and the createdAt/deliveredAt/cancelledAt/failedAt timestamps.
8.6 Get tracking
GET /api/v1/orders/{platformOrderId}/tracking{
"platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
"shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"unifiedStatus": "OnTheWay",
"driverName": "Mohammed",
"driverPhone": "0590000000",
"driverLat": 31.9038,
"driverLng": 35.2034,
"driverLocationUpdatedAt": "2026-09-22T13:40:00Z",
"trackingUrl": "https://tracking.example.com/abc",
"currentEta": "2026-09-22T14:05:00Z"
}Every field here is nullable. You'll see null when there's no shipment yet, or simply because the current Delivery Provider doesn't supply that signal — not every provider sends live driver coordinates, a tracking URL, or an ETA. Presence is provider-dependent; don't count on it universally.
8.7 Get full tracking history
GET /api/v1/orders/{platformOrderId}/tracking-historyReturns every recorded tracking/status event for the order's shipment, oldest first, as a plain array (empty, not an error, if no shipment exists yet):
[
{
"eventTimeUtc": "2026-09-22T13:28:54Z",
"receivedAtUtc": "2026-09-22T13:28:55Z",
"status": "ArrivedAtPickup",
"providerStatus": "arrived_at_store",
"source": "Webhook",
"driverName": "Mohammed",
"driverPhone": "0590000000",
"driverLat": 31.9038,
"driverLng": 35.2034,
"estimatedDeliveryAtUtc": "2026-09-22T14:05:00Z",
"providerCorrelationId": "DLV-9001"
}
]status is always a UnifiedDeliveryStatus value (Section 8.3), the normalized, provider-agnostic status. providerStatus and providerCorrelationId are different — they're opaque, best-effort diagnostic text straight from the Delivery Provider's own raw event. Useful for support and debugging, but not a stable contract: exact values differ per provider and per integration, and FleetBridge makes no promises about their format. Build your business logic against status, never against providerStatus. source is one of Webhook, Polling, Platform (FleetBridge's own administrative actions).
9. Webhooks — FleetBridge → you
9.1 Direction
This section flips the direction: FleetBridge is calling your server now, not the other way around like everything in Sections 7 and 8:
Order Source ◄──HTTPS POST── FleetBridge (this section)
Order Source ──HTTPS POST──► FleetBridge (Sections 7, 8, 11, 12)9.2 How your callback URL is configured
FleetBridge registers your webhook callback URL and signing secret for you (through your tenant's dashboard user) as part of onboarding. An Order Source API key can't create or modify its own webhook endpoint registration. You get the secret once, at registration time — capture it right then, because FleetBridge can't show it to you again later. Rotating it is possible (Section 9.10); redisplaying the old one isn't.
You can, though, trigger a one-off test delivery to your own registered endpoint with your API key:
POST /api/v1/webhooks/testThis fires a webhook.test event (Section 9.9) at your registered URL, signed exactly like any real event, so you can check connectivity and signature verification before going live.
9.3 Delivery mechanics
Every webhook is an HTTP POST with Content-Type: application/json to your registered URL. A 2xx counts as acknowledged. Anything else — non-2xx, timeout, connection failure — counts as a failure and gets retried per the schedule below. FleetBridge waits 15 seconds for your response, so respond fast and push any slow processing to the background on your side.
9.4 Retry schedule
If your endpoint doesn't return 2xx, FleetBridge retries up to 5 times after the initial attempt (6 attempts total), at increasing delays:
attempt 1 (immediate) → fail
+1 minute → attempt 2
+5 minutes → attempt 3
+15 minutes → attempt 4
+1 hour → attempt 5
+3 hours → attempt 6 → still failing → delivery marked Exhausted, no further automatic retryEach attempt's number rides along in the X-Platform-Retry-Count header (0 on the first try). An Exhausted delivery isn't gone forever — a FleetBridge operator can still resend it manually. It's just done retrying on its own.
9.5 At-least-once delivery — you must deduplicate
FleetBridge's webhook delivery is at-least-once, not exactly-once, and not guaranteed in-order. In rare recovery scenarios the same logical event can land on your server twice, and two different events for the same order can arrive out of order relative to each other — a fast retry of an older event racing a newer event's first attempt, for example. So your webhook handler needs to be:
- Idempotent: dedupe on the
eventIdfield (it's also in theX-Platform-Event-Idheader). Processing the sameeventIdtwice should have zero additional effect the second time. - Order-tolerant: use
eventTime, or for delivery-status events thedelivery.statusvalue itself against whatever you last recorded, to decide if an incoming event is actually newer than what you already have. Don't assume events arrive in the order they happened.
9.6 Headers on every webhook request
POST /your/callback/url HTTP/1.1
Content-Type: application/json
X-Platform-Event-Id: evt_9f1c2b3a4d5e6f708192a3b4c5d6e7f8
X-Platform-Timestamp: 2026-09-22T13:20:00Z
X-Platform-Signature: sha256=1a2b3c4d5e6f...
X-Platform-Retry-Count: 0
X-Platform-Api-Version: v1Section 10 (Webhook Security) covers exactly how X-Platform-Signature gets computed and how to verify it. Don't skip it before going to production.
FleetBridge doesn't enforce a server-side replay window — no built-in expiry on how old a valid signature can be. If your security posture needs old or replayed requests rejected, that's on you to build: an X-Platform-Timestamp freshness check (rejecting anything older than, say, 5 minutes) as part of your own verification code. The worked examples in Section 10.5 show how.
9.7 Event catalog
| Event type | Fires when |
|---|---|
order.created | The order was created inside FleetBridge. |
order.updated | Order business data was changed via Update (Section 11); includes per-field propagation results. |
delivery.provider_assigned | A Delivery Provider was selected for this dispatch round. |
delivery.sent_to_provider | The order was actually sent to that provider. |
delivery.accepted | The provider accepted the delivery. |
driver.assigned | A driver was assigned. |
driver.location_updated | Driver coordinates changed. |
tracking.updated | The tracking URL changed. |
delivery.arrived_at_pickup | The driver arrived at the branch. |
delivery.picked_up | The driver collected the order. |
delivery.on_the_way | The order is en route. |
eta.updated | The estimated delivery time changed. |
sla.at_risk | The order is at risk of breaching its configured SLA. |
sla.breached | The order breached its configured SLA. |
delivery.delivered | The order was delivered. |
order.cancellation_requested | A cancellation was accepted into the workflow; provider confirmation is pending. |
delivery.cancelled | The delivery was cancelled and confirmed. |
order.cancellation_failed | A provider-side cancellation attempt failed; the order needs manual attention. |
delivery.failed | The delivery failed terminally (not a return case). |
delivery.return_requested | A post-pickup failure triggered a return. |
delivery.returning_to_origin | Goods are on the way back to the branch. |
delivery.returned_to_origin | Goods are back at the branch. |
delivery.return_failed | The return itself could not be completed. |
provider.failed | The current provider failed and FleetBridge is trying the next eligible one (see Section 15.3). |
order.no_provider_available | Every eligible provider was exhausted. |
order.manual_review_required | The order needs FleetBridge operator attention. |
webhook.test | A manually triggered connectivity test (Section 9.2) — different payload shape, see 9.9. |
You don't need to subscribe to every event type. Subscriptions are configured per callback URL by FleetBridge on your behalf during onboarding — just tell them which ones you want.
9.8 Standard payload shape
Every event except webhook.test (9.9) uses this shape. Sections that don't apply to a given event are null — for example driver/tracking/eta are all null on an order.created event, since no shipment exists yet.
{
"eventId": "evt_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
"eventType": "delivery.accepted",
"eventTime": "2026-09-22T13:20:00Z",
"apiVersion": "v1",
"tenantId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
"orderSource": { "id": "8a1b2c3d-4e5f-4a3b-8c2d-1e0f9a8b7c6d", "code": "qr_menu", "name": "QR Menu" },
"order": {
"platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
"externalOrderId": "ORD-2003",
"branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"orderStatus": "InDelivery"
},
"delivery": {
"shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"platformReference": "att_18c9a4f2b3c1a2b3c4d5e6f708192a3b",
"providerCode": "cervo",
"providerDeliveryId": "DLV-9001",
"status": "ProviderAccepted"
},
"driver": null,
"tracking": null,
"eta": null,
"sla": { "isAtRisk": false, "isBreached": false, "breachedStages": [] },
"failure": null,
"routing": null,
"updatePropagation": null
}Field reference:
| Path | Type | Notes |
|---|---|---|
eventId | string | Globally unique. Your deduplication key. |
eventType | string | One of Section 9.7. |
eventTime | ISO 8601 UTC | When FleetBridge recorded the event. |
apiVersion | string | Always "v1" today. |
tenantId | GUID | Your tenant. |
orderSource.{id,code,name} | Always your own Order Source. | |
order.platformOrderId | GUID | Matches what Create returned. |
order.orderStatus | string | OrderStatus value, Section 8.2. |
delivery.status | string | UnifiedDeliveryStatus value, Section 8.3. delivery itself is null before dispatch. |
delivery.platformReference | string | An internal correlation id, format att_<hex>. Not the same as providerDeliveryId. |
delivery.providerDeliveryId | string, nullable | The Delivery Provider's own id for this delivery, when the provider exposes one. |
driver.{name,phone,lat,lng} | null until a driver is assigned; individual fields may still be null afterward depending on the provider. | |
tracking.trackingUrl | string, nullable | Provider-hosted tracking page, when the provider supplies one. |
eta.estimatedDeliveryAt / remainingMinutes / confidence | Best-effort; not every provider supplies an ETA. | |
sla.{isAtRisk,isBreached,breachedStages} | Reflects your tenant's configured SLA thresholds. | |
failure.{reasonCode,reasonText,rawProviderReason} | Populated on provider.failed/delivery.failed/cancellation-failure events. | |
routing.{nextAction,nextProviderCode} | Populated on provider.failed — see Section 15.3. | |
updatePropagation.fields | object | Populated only on order.updated — mirrors the per-field propagation result from the Update response (Section 11). |
9.9 webhook.test payload (different shape)
{
"eventId": "evt_test_1a2b3c4d5e6f7081",
"eventType": "webhook.test",
"eventTime": "2026-09-22T13:00:00Z",
"apiVersion": "v1",
"tenantId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
"orderSourceId": "8a1b2c3d-4e5f-4a3b-8c2d-1e0f9a8b7c6d",
"message": "This is a test event from FleetBridge to verify your webhook endpoint is reachable and correctly signed."
}webhook.test is intentionally flat, with no order/delivery/orderSource nested objects. If your handler assumes every event has the full Section 9.8 shape, it'll break on this one — check eventType first and branch your parsing from there.
9.10 Secret rotation
If FleetBridge rotates your webhook signing secret, you get a 24-hour overlap window where both the old and new secret are valid. During that window, X-Platform-Signature carries both signatures, comma-separated, newest first:
X-Platform-Signature: sha256=<hex-with-new-secret>,sha256=<hex-with-old-secret>Your verification code needs to accept the request if any of the comma-separated values matches what you compute. Don't assume there's exactly one value in this header.
10. Webhook signature verification
Don't skip this section. An unverified webhook is just a POST request from the internet with no authentication behind it.
10.1 What is signed
The signing input is the concatenation, in this exact order, of four values, with no delimiter between them:
signingInput = apiVersion + timestamp + eventId + rawRequestBodyapiVersion— the literal stringv1, always.timestamp— the exact string value of theX-Platform-Timestampheader (not a re-formatted version of it).eventId— the exact string value of theX-Platform-Event-Idheader.rawRequestBody— the exact raw bytes of the HTTP request body, before any JSON parsing — see 10.4 for why this matters.
10.2 Which secret
Your per-endpoint webhook signing secret, handed to you once at registration. Format is whsec_ followed by 64 lowercase hex characters — structurally similar to your X-Api-Key, but a different credential. Never send it to FleetBridge or anyone else. It's used only locally, by you, to verify.
10.3 Algorithm
HMAC-SHA256 over the UTF-8 bytes of signingInput, keyed by the UTF-8 bytes of your secret, hex-encoded in lowercase. The header value is prefixed sha256=:
X-Platform-Signature: sha256=<64 lowercase hex characters>(During a secret-rotation overlap window, the header may contain two comma-separated sha256=... values — see Section 9.10.)
10.4 Why you must use the raw body
FleetBridge signs the exact bytes it sent — not a value derived from re-serializing the parsed JSON. Here's the trap: most web frameworks parse the JSON body before your signature-verification code even runs. If you then re-serialize that parsed object to build your comparison string, key ordering, whitespace, or number formatting can drift just enough to produce a different byte sequence — and a signature "mismatch" that has nothing to do with an actual security problem. Capture and verify against the raw, unparsed body bytes, before or independent of JSON parsing, no matter which language you're in.
10.5 Verification steps (all languages)
- Read the raw request body as bytes (or a string, using the same encoding your framework received it in — UTF-8) before any JSON deserialization.
- Read the
X-Platform-Timestamp,X-Platform-Event-Id, andX-Platform-Signatureheaders. - (Optional, recommended) Check that
X-Platform-Timestampis within your own acceptable freshness window (Section 9.6 — FleetBridge does not enforce one for you). - Build
signingInput = "v1" + timestamp + eventId + rawBody. - Compute
HMAC-SHA256(secret, signingInput), hex-encode it in lowercase. - Split
X-Platform-Signatureon commas. For each candidate value, strip thesha256=prefix and compare it to your computed value using a constant-time comparison (never==/.equalson secret-derived strings) — accept if any candidate matches. - Only after verification succeeds, parse the body as JSON and process the event.
10.6 C#
using System.Security.Cryptography;
using System.Text;
public static bool VerifyFleetBridgeWebhook(
string rawBody, string timestamp, string eventId, string signatureHeader, string secret)
{
var signingInput = "v1" + timestamp + eventId + rawBody;
var computedBytes = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(signingInput));
var computedHex = Convert.ToHexString(computedBytes).ToLowerInvariant();
foreach (var candidate in signatureHeader.Split(','))
{
var trimmed = candidate.Trim();
if (!trimmed.StartsWith("sha256=", StringComparison.Ordinal))
{
continue;
}
var presentedHex = trimmed["sha256=".Length..];
var presentedBytes = Encoding.UTF8.GetBytes(presentedHex);
var computedHexBytes = Encoding.UTF8.GetBytes(computedHex);
if (presentedBytes.Length == computedHexBytes.Length &&
CryptographicOperations.FixedTimeEquals(presentedBytes, computedHexBytes))
{
return true;
}
}
return false;
}
// ASP.NET Core minimal API example — read the RAW body before model binding:
app.MapPost("/fleetbridge/webhooks", async (HttpRequest request) =>
{
request.EnableBuffering();
using var reader = new StreamReader(request.Body, Encoding.UTF8, leaveOpen: true);
var rawBody = await reader.ReadToEndAsync();
request.Body.Position = 0;
var timestamp = request.Headers["X-Platform-Timestamp"].ToString();
var eventId = request.Headers["X-Platform-Event-Id"].ToString();
var signature = request.Headers["X-Platform-Signature"].ToString();
if (!VerifyFleetBridgeWebhook(rawBody, timestamp, eventId, signature, YourStoredSecret))
{
return Results.Unauthorized();
}
// Only now parse rawBody as JSON and process the event, deduplicating on eventId.
return Results.Ok();
});10.7 JavaScript (Node.js)
const crypto = require("crypto");
function verifyFleetBridgeWebhook(rawBody, timestamp, eventId, signatureHeader, secret) {
const signingInput = "v1" + timestamp + eventId + rawBody;
const computedHex = crypto.createHmac("sha256", secret).update(signingInput, "utf8").digest("hex");
return signatureHeader.split(",").some((candidate) => {
const trimmed = candidate.trim();
if (!trimmed.startsWith("sha256=")) return false;
const presentedHex = trimmed.slice("sha256=".length);
const presented = Buffer.from(presentedHex, "utf8");
const computed = Buffer.from(computedHex, "utf8");
return presented.length === computed.length && crypto.timingSafeEqual(presented, computed);
});
}
// Express example — you MUST capture the raw body before express.json() parses it.
const express = require("express");
const app = express();
app.use(
"/fleetbridge/webhooks",
express.raw({ type: "application/json" }), // gives req.body as a Buffer, unparsed
);
app.post("/fleetbridge/webhooks", (req, res) => {
const rawBody = req.body.toString("utf8");
const timestamp = req.header("X-Platform-Timestamp");
const eventId = req.header("X-Platform-Event-Id");
const signature = req.header("X-Platform-Signature");
if (!verifyFleetBridgeWebhook(rawBody, timestamp, eventId, signature, process.env.FLEETBRIDGE_WEBHOOK_SECRET)) {
return res.status(401).end();
}
const event = JSON.parse(rawBody);
// Deduplicate on event.eventId, then process.
res.status(200).end();
});10.8 Python
import hashlib
import hmac
def verify_fleetbridge_webhook(raw_body: bytes, timestamp: str, event_id: str, signature_header: str, secret: str) -> bool:
signing_input = ("v1" + timestamp + event_id).encode("utf-8") + raw_body
computed_hex = hmac.new(secret.encode("utf-8"), signing_input, hashlib.sha256).hexdigest()
for candidate in signature_header.split(","):
candidate = candidate.strip()
if not candidate.startswith("sha256="):
continue
presented_hex = candidate[len("sha256="):]
if hmac.compare_digest(presented_hex, computed_hex):
return True
return False
# Flask example — request.get_data() returns the raw, unparsed body.
from flask import Flask, request, abort
app = Flask(__name__)
@app.route("/fleetbridge/webhooks", methods=["POST"])
def fleetbridge_webhook():
raw_body = request.get_data() # bytes, raw — read before request.get_json()
timestamp = request.headers.get("X-Platform-Timestamp", "")
event_id = request.headers.get("X-Platform-Event-Id", "")
signature = request.headers.get("X-Platform-Signature", "")
if not verify_fleetbridge_webhook(raw_body, timestamp, event_id, signature, FLEETBRIDGE_WEBHOOK_SECRET):
abort(401)
event = request.get_json()
# Deduplicate on event["eventId"], then process.
return "", 20011. Update Order
PATCH /api/v1/orders/{platformOrderId}11.1 Partial-update semantics — read this before building your client
The request body only ever describes the fields you want to change. There are three distinct states for every field:
- Omit the field from the JSON body entirely → left unchanged.
- Send the field with an explicit
null(only meaningful for fields that are nullable, likecustomerEmailornotes) → clears it. - Send the field with a value → sets it to that value.
This means {} is a valid (no-op) request body, and you must not send a field just because your own internal object happens to have that property populated — only send what actually changed.
11.2 Mutable fields
| Field | Notes |
|---|---|
customerName | |
customerPhone | |
customerEmail | Nullable — send null to clear. |
dropoff.address | Independent of dropoff.lat/dropoff.lng — patching one doesn't reset the others. |
dropoff.lat / dropoff.lng | |
notes | Nullable. |
paymentMethod | |
paymentMethodRaw | Nullable. |
amount | |
deliveryFee | Nullable. |
currency | Re-normalized to uppercase; a same-currency different-casing PATCH is treated as a no-op. |
preparationTimeMinutes | |
scheduledDeliveryAt | Nullable; see restriction below. |
11.3 Immutable fields
externalOrderId, externalOrderNumber, branchId/pickup location, and the routing/provider selection fields can't be changed through Update — send them anyway and they're just silently ignored, since they're not even part of the request schema. Need a different branch? Cancel and recreate the order. Need a different provider? That happens through cancellation too, never through Update.
11.4 Example: Request → Success
{
"customerPhone": "+970590000111",
"notes": "Leave with the neighbor if no answer",
"amount": 92.00
}HTTP/1.1 200 OK{
"orderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
"addressPropagation": "NotApplicable",
"phonePropagation": "Propagated",
"scheduledDeliveryPropagation": "NotApplicable",
"notesPropagation": "Propagated",
"customerNamePropagation": "NotApplicable",
"customerEmailPropagation": "NotApplicable",
"amountPropagation": "Propagated",
"currencyPropagation": "NotApplicable",
"paymentMethodPropagation": "NotApplicable",
"deliveryFeePropagation": "NotApplicable",
"preparationTimePropagation": "NotApplicable"
}FleetBridge always saves your update on its own side first, whether or not the active Delivery Provider can accept the change. The response then tells you, field by field, what happened when FleetBridge tried to forward that specific change to whoever's handling the delivery right now:
| Value | Meaning |
|---|---|
Propagated | Successfully forwarded to the Delivery Provider. |
NotSupportedByProvider | The current provider's integration doesn't support changing this field once a delivery is in flight. Your change is saved in FleetBridge, but the provider (and its driver) may not see it. |
PropagationFailed | FleetBridge tried to forward the change and the provider call failed (transient/technical). Your change is still saved in FleetBridge. |
NotApplicable | This field wasn't part of your request, or there is no active shipment yet to propagate to. |
A NotSupportedByProvider or PropagationFailed result isn't an HTTP error by itself — the update succeeded from FleetBridge's point of view. But if a field's real-world propagation matters to you (a changed dropoff address after the driver's already en route, say), check that specific field in the response and handle a non-Propagated result in your own UI or ops process. FleetBridge won't escalate it to an operator on your behalf.
11.5 Updating never changes order status
Update never pushes orderStatus/delivery.status forward or back. Change a customer's phone number on an order that's DriverAssigned and it stays DriverAssigned — it can't slip back to PendingRouting, and it can't jump ahead either. Lifecycle transitions only happen through routing, Delivery Provider events, Cancel, and FleetBridge's own operator workflows.
11.6 Scheduled-delivery-specific restriction
You can change scheduledDeliveryAt only while the shipment hasn't progressed past ProviderAccepted — unless the current Delivery Provider explicitly supports updating a scheduled time after acceptance. Otherwise you'll get 400 PROVIDER_UPDATE_NOT_SUPPORTED.
11.7 Invalid update example
{ "amount": -5 }HTTP/1.1 400 Bad Request
Content-Type: application/problem+json{
"status": 400,
"title": "Bad Request",
"detail": "'amount' must not be negative.",
"errorCode": "INVALID_AMOUNT",
"correlationId": "0HNOOIIC1J8FA:00000002"
}11.8 When Update is rejected outright
| errorCode | Status | Cause |
|---|---|---|
ORDER_ALREADY_FINAL | 409 | The order is Delivered, Cancelled, or Failed. |
PROVIDER_UPDATE_NOT_SUPPORTED | 400 | scheduledDeliveryAt change rejected per Section 11.6. |
| (validation errors) | 400 | Same field-length/amount/payment-method rules as Create, Section 7.5, applied to the merged (post-patch) values. |
12. Cancel Order
POST /api/v1/orders/{platformOrderId}/cancelOptional body:
{ "reason": "customer_requested" }reason is a free-text string, ≤500 characters, entirely optional. Skip the body altogether if you've got nothing to say.
12.1 Behavior by stage
| Order / delivery stage | What happens |
|---|---|
Created, Scheduled, PendingRouting — nothing dispatched yet | Cancelled immediately, platform-side. No call to any Delivery Provider. outcome: "Cancelled". |
Dispatching — sent to a provider, not yet accepted | Open delivery attempts are cancelled; FleetBridge notifies the provider best-effort. Order becomes Cancelled immediately once no attempt remains active. outcome: "Cancelled". |
InDelivery, before pickup (ProviderAccepted / DriverAssigned / ArrivedAtPickup) | Allowed only if the current Delivery Provider supports cancellation before pickup. If not supported: rejected, 409 CANCELLATION_NOT_SUPPORTED_AT_STAGE. If supported: order moves to CancellationRequested and FleetBridge waits for the provider to confirm; outcome: "ConfirmationPending". |
InDelivery, after pickup (PickedUp / OnTheWay) | Allowed only if the current Delivery Provider supports cancellation after pickup (this is uncommon — most providers do not). If not supported: 409 CANCELLATION_NOT_SUPPORTED_AT_STAGE. If supported: same CancellationRequested / ConfirmationPending flow as above. |
Any final status (Delivered/Cancelled/Failed) | Rejected: 409 ORDER_ALREADY_FINAL. |
Once pickup has happened and the provider doesn't support after-pickup cancellation, there are only two ways forward: delivery, or a provider-side failure that FleetBridge handles as a Return (Section 18). There's no "force cancel a physically-picked-up order" button available to an Order Source — it just doesn't exist.
12.2 Response
HTTP/1.1 200 OK{
"orderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
"status": "CancellationRequested",
"outcome": "ConfirmationPending"
}outcome is either Cancelled (finalized right away) or ConfirmationPending (waiting on the provider). Watch for the delivery.cancelled webhook — or order.cancellation_failed if the provider-side cancellation itself fails, in which case the order moves to ManualReviewRequired instead of sitting in limbo forever. FleetBridge never marks an order Cancelled while a provider that already accepted it hasn't actually confirmed.
12.3 Idempotent repeated cancellation
Calling Cancel again on an order that's already CancellationRequested or already Cancelled is safe. A repeat call on an already-final Cancelled order comes back 409 ORDER_ALREADY_FINAL, which you can just treat as "already cancelled, nothing to do" in your retry logic. A repeat call while still CancellationRequested won't create a duplicate cancellation attempt either.
12.4 Related: look up by your own reference
GET /api/v1/orders/by-external-id/{externalOrderId}Same shape as GET /api/v1/orders/{platformOrderId}, scoped to orders your Order Source created. Handy if you need to re-establish platformOrderId from your own stored externalOrderId before calling Update or Cancel — after a crash, say, where you're not sure whether you'd already persisted the FleetBridge id. Lookup is by externalOrderId only; externalOrderNumber is never a lookup key.
13. Idempotency
13.1 Header
Idempotency-Key: <your own unique string, ≤200 characters>Supported only on Create (POST /api/v1/orders). Update and Cancel don't accept or need one — Cancel is naturally idempotent already (Section 12.3), and Update's partial-patch semantics mean a retried identical PATCH just re-applies the same, already-applied change harmlessly.
13.2 Scope
An idempotency key is scoped to (your tenant, your Order Source, the key string). So two different Order Sources under the same tenant can reuse the identical key string with zero risk of collision.
13.3 Behavior on repeat — same key, read carefully
Say you send a second Create request with an Idempotency-Key that already succeeded once.
FleetBridge returns the original order, unconditionally: 201 Created, the same platformOrderId, the same response shape as the first call — whether or not the new request body matches the original.
There's no payload-equality check, and no "conflicting payload" error. Replay the same key with a genuinely different body — a bug on your side, or a legitimate change of mind — and FleetBridge does not create a second order and does not apply your new body to the existing one. It just quietly hands back the original order, exactly as it already was. Need to change something about an order you already created? Use Update (Section 11). Never a second Create with the same key and different fields.
13.4 Behavior with no idempotency key
Skip Idempotency-Key entirely and FleetBridge still protects you from an accidental true duplicate: a second Create with the same externalOrderId (scoped to your Order Source) resolves to the existing order the same way a matching Idempotency-Key would. You get the original back, not a new one. externalOrderId itself is always a de-dup key, with or without an explicit Idempotency-Key header. externalOrderNumber never is: two orders may share one. We'd still recommend sending the header explicitly — it lets you retry safely with the *same* externalOrderId semantics even in flows where you generate that id late, and it says what you mean more clearly than relying on a side effect.
13.5 Retention
Idempotency records stick around indefinitely. There's no expiry after which the same key could suddenly create a second order — it's permanently tied to whatever it first created.
13.6 What to do after a timeout / unknown outcome
Create request times out, or you get a network error with no HTTP response at all — now you can't tell if FleetBridge actually processed it. The right move: retry the exact same request, including the same Idempotency-Key. Whether the original attempt succeeded or never arrived, that retry is safe. You'll either get the freshly created order or the original one back. Don't generate a new Idempotency-Key for what you think is a retry of the same logical order — that defeats the whole mechanism and can actually create a duplicate.
13.7 Worked examples
First request:
POST /api/v1/orders
Idempotency-Key: web-order-7781
{ "externalOrderId": "WEB-7781", "payment": { "method": "Cash", "amount": 50, "currency": "ILS" }, ... }
→ 201 Created, platformOrderId = "aaa...", externalOrderId = "WEB-7781"Exact retry (same key, same body) — safe, expected:
POST /api/v1/orders
Idempotency-Key: web-order-7781
{ "externalOrderId": "WEB-7781", "payment": { "method": "Cash", "amount": 50, "currency": "ILS" }, ... }
→ 201 Created, platformOrderId = "aaa..." (identical to the first response)Same key, different body — still returns the original, does NOT apply the new body:
POST /api/v1/orders
Idempotency-Key: web-order-7781
{ "externalOrderId": "WEB-7781", "payment": { "method": "Card", "amount": 999, "currency": "ILS" }, ... }
→ 201 Created, platformOrderId = "aaa..." — still Cash/50, the ORIGINAL order, unchanged14. Scheduled orders
14.1 Semantics
scheduledDeliveryAtomitted ornull→ immediate (ASAP) order, dispatched under your tenant's normal immediate-routing rules right away.scheduledDeliveryAtset to a future timestamp → the order is created withstatus: "Scheduled"and dispatched automatically when due.
14.2 Validation
scheduledDeliveryAt needs to be at least a minimum lead time out — 15 minutes by FleetBridge's platform default, though your tenant might be configured differently. Treat 15 minutes as the floor to design against, not a guarantee. Anything before that minimum, or in the past, gets rejected:
{
"status": 400,
"title": "Bad Request",
"detail": "scheduledDeliveryAt must be at least 15 minutes in the future.",
"errorCode": "INVALID_SCHEDULED_TIME",
"correlationId": "..."
}Must be ISO 8601 with an explicit UTC offset (Section 6).
14.3 Dispatch timing
FleetBridge doesn't wait until the exact scheduledDeliveryAt moment to start dispatching. It starts ahead of time, so the delivery actually has a shot at arriving on schedule:
dispatchAt = scheduledDeliveryAt − dispatchLeadTimeMinutesdispatchLeadTimeMinutes is a per-tenant setting (30 minutes by platform default) that can be overridden per branch. You don't send this value at all — it's purely a FleetBridge/tenant configuration concern. At dispatchAt, the order moves from Scheduled to PendingRouting and enters normal routing.
14.4 While scheduled
A Scheduled order can be updated (Section 11) and cancelled (Section 12) freely. Cancellation before dispatch is always platform-side only, since no provider is involved yet. SLA timers don't start until the order actually dispatches — not at creation time.
14.5 Example
{
"externalOrderId": "ORD-3010",
"externalBranchId": "MAIN-BRANCH",
"scheduledDeliveryAt": "2026-09-23T09:00:00+03:00",
"pickup": { "address": "Main Branch", "lat": 31.9021, "lng": 35.2034 },
"dropoff": { "customerName": "Layla Odeh", "customerPhone": "+970598765432", "address": "Al-Masyoun", "lat": 31.9130, "lng": 35.2010 },
"payment": { "method": "Online", "amount": 65, "currency": "ILS" },
"preparationTimeMinutes": 10
}{
"platformOrderId": "7f2d1a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b",
"externalOrderId": "ORD-3010",
"externalOrderNumber": "ORD-3010",
"status": "Scheduled",
"branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"routingMode": "PriorityFailover",
"createdAt": "2026-09-22T14:00:00Z"
}15. Provider routing and failover
15.1 You integrate with FleetBridge, not with a Delivery Provider
Order Source
│
▼
FleetBridge Order API ← this document
│
▼
Routing / Orchestration (FleetBridge-internal — provider selection, failover, retries)
│
▼
Delivery Provider ← you never see this layer directlyYou never get Delivery Provider credentials, never see its webhook format, and never need to know how FleetBridge's internal adapter for a given provider actually works. delivery.providerCode/delivery.providerDeliveryId, when present, are informational — handy for support conversations and driver-facing tracking links, but not something your integration logic should branch on.
15.2 Requesting a specific provider (optional)
You can set deliveryProviderCode on Create to request a specific Delivery Provider by its FleetBridge-known code ("cervo", say). It's honored only if:
- The provider is known and enabled for your tenant.
- Manual provider selection is permitted for the branch/tenant.
- The provider is currently eligible — enabled, active credentials, allowed for this branch.
Unknown or not-enabled code: 400 PROVIDER_NOT_ENABLED. Real, known provider but the override isn't currently honorable (disabled for this branch, credentials not configured, manual override turned off for your tenant): 400 MANUAL_OVERRIDE_NOT_ALLOWED. Leave the field out entirely and FleetBridge picks the provider per your tenant's normal routing configuration — the default, and the right choice unless you have a specific reason to override it for a given order.
15.3 Failover — what you observe, and what you should do
Before pickup, if a Delivery Provider fails — rejects, times out, cancels — FleetBridge may automatically route the order to another eligible one, depending on your tenant's routing mode. Here's what you'll see:
{ "eventType": "provider.failed", "delivery": { "providerCode": "cervo", "attemptStatus": "CancelledByProvider" },
"failure": { "reasonCode": "NO_DRIVERS_AVAILABLE", "reasonText": "No drivers available", "rawProviderReason": "No couriers nearby" },
"routing": { "nextAction": "RetryingWithNextProvider", "nextProviderCode": "provider_b" } }If a next provider is found, that's followed by the normal delivery.provider_assigned / delivery.sent_to_provider sequence again, just for the new provider — same platformOrderId, same externalOrderId. If every eligible provider gets exhausted, routing.nextAction becomes NoProviderAvailable, you get order.no_provider_available, and the order status becomes NoProviderAvailable (held, Section 8.2) until a FleetBridge operator steps in.
What you actually need to do: keep correlating on platformOrderId/externalOrderId. Never create a second order because a provider failed — that's exactly the scenario failover exists to handle transparently for you. Don't key any of your own logic off providerCode either, since it can legitimately change mid-order. And failover only happens before pickup — once the order is physically picked up, a delivery problem becomes a Return (Section 18), never a silent re-dispatch to a different provider.
16. Error model
Every business-logic rejection (as opposed to a raw authentication failure, Section 2.5, or malformed-JSON parse failure) comes back in this shape, content-type: application/problem+json:
{
"status": 404,
"title": "Not Found",
"detail": "No active branch was found for the provided branchId or pickup location.",
"errorCode": "BRANCH_NOT_FOUND",
"details": { "pickupLat": 31.9021, "pickupLng": 35.2034 },
"correlationId": "0HNOOIIC1J8FA:00000003"
}details shows up only for some error codes, when FleetBridge has specific structured context to offer. correlationId is there whenever available, and worth logging — include it if you ever need to ask FleetBridge support about a specific failed request.
16.1 Status code matrix
| HTTP | Meaning here | Retryable? | Typical client action |
|---|---|---|---|
| 400 | Request failed validation (bad field value, bad JSON, missing required field). | No — fix the request first. | Correct the field named in detail/errorCode and resend with a new logical attempt (existing Idempotency-Key, if any, is unaffected since no order was created). |
| 401 | Missing/invalid/expired/revoked API key. Empty body — see Section 2.5. | No, unless you can fix the credential. | Check the X-Api-Key header is present, well-formed, and current. |
| 403 | Authenticated, but your Order Source or Tenant cannot act right now (disabled/suspended). | No. | Contact FleetBridge/your tenant admin; this is a configuration state, not a transient fault. |
| 404 | The referenced order (or branch, on Create) does not exist, or does not belong to your Order Source. | No. | Re-check the id; if you expected it to exist, look it up again via GET .../by-external-id/{externalOrderId}. |
| 409 | The request is well-formed, but conflicts with the order's current state (already final, cancellation not supported at this stage). | No — the state itself needs to change first, if it ever will. | Read the order's current status before deciding what to do next; do not blindly retry a 409. |
| 429 | Rate limited. See Section 22. | Yes, after the delay in Retry-After. | Back off and retry; safe to retry a Create with the same Idempotency-Key. |
| 5xx | An unexpected server-side fault. | Situational — see below. | See 16.2. |
16.2 On a 5xx or no response at all
Don't blindly retry every 5xx with a brand-new request. For Create specifically, always retry with the same Idempotency-Key (Section 13.6) — that's what makes a 5xx/timeout retry safe, regardless of whether the original request actually succeeded server-side before failing to respond. Update and Cancel are naturally safe to retry as-is (Update re-applies the same patch; Cancel is idempotent, Section 12.3), so a plain retry with backoff works fine there. Use increasing backoff between attempts — 1s, 2s, 5s, say — rather than hammering it in a tight loop.
16.3 Full error code reference (Order-Source-relevant)
| errorCode | HTTP | Where you'll see it |
|---|---|---|
BRANCH_NOT_FOUND | 404 | Create — Section 7.5, 19. |
INVALID_PICKUP_LOCATION | 400 | Create — bad pickup.lat/lng. |
INVALID_DROPOFF_LOCATION | 400 | Create/Update — bad dropoff.lat/lng. |
INVALID_AMOUNT | 400 | Create/Update — negative amount/deliveryFee. |
STRUCTURAL_LIMIT_EXCEEDED | 400 | Create/Update — string too long, or amount precision/size. |
INVALID_PREPARATION_TIME | 400 | Create/Update — negative preparationTimeMinutes. |
INVALID_PAYMENT_METHOD | 400 | Create/Update — unrecognized payment.method. |
INVALID_SCHEDULED_TIME | 400 | Create/Update — scheduledDeliveryAt too soon. |
PROVIDER_NOT_ENABLED | 400 | Create — unknown/disabled deliveryProviderCode. |
MANUAL_OVERRIDE_NOT_ALLOWED | 400 | Create — provider override not currently honorable. |
PROVIDER_UPDATE_NOT_SUPPORTED | 400 | Update — scheduledDeliveryAt change rejected post-acceptance. |
TENANT_SUSPENDED | 403 | Any call — Section 2.5. |
ORDER_SOURCE_DISABLED | 403 | Any call — Section 2.5. |
INVALID_API_KEY | 403 | Rare/abnormal caller-context mismatch. |
ORDER_NOT_FOUND | 404 | Any order-scoped call — wrong id, or belongs to a different Order Source. |
ORDER_ALREADY_FINAL | 409 | Update/Cancel on Delivered/Cancelled/Failed. |
CANCELLATION_NOT_SUPPORTED_AT_STAGE | 409 | Cancel — Section 12.1. |
RATE_LIMIT_EXCEEDED | 429 | Section 22. |
DUPLICATE_ORDER and IMMUTABLE_FIELD aren't real runtime error codes you'll ever actually receive. Duplicate Create requests get handled transparently by idempotent replay (Section 13), and immutable fields just aren't part of the Update schema in the first place (Section 11.3) — there's nothing to error on.
17. PaymentMethod
"payment": { "method": "Cash", "methodRaw": "cash_on_delivery" }method (required on Create) is one of exactly five values:
Cash | Card | Online | Wallet | OthermethodRaw (optional) lets you keep your own original label alongside the normalized value. Handy if your system has a richer payment taxonomy than FleetBridge's five buckets — map whatever doesn't fit cleanly to Other and put your real value in methodRaw.
PaymentMethod is order metadata, nothing more. FleetBridge is not a payment processor. Setting method: "Cash" doesn't make FleetBridge collect, hold, settle, or reconcile any cash-on-delivery funds — that stays entirely between you, your Delivery Provider, and your customer. FleetBridge just passes the value through to the Delivery Provider where its contract accepts it, and reports it back to you. It never affects routing or provider selection.
18. Returns
Phase 1 has no self-service return action for an Order Source. If a delivery fails after physical pickup — customer unreachable, refuses delivery, address unusable, provider cancels mid-route — FleetBridge doesn't silently re-dispatch to another provider. Normal failover stops at pickup (Section 15.3). Instead, the order enters a return flow that a FleetBridge operator resolves by hand. There's no API call an Order Source can make to trigger, speed up, or resolve a return.
What you *can* do:
- Observe.
orderStatusbecomesReturnInProgresswhile the return is active, andFailedonce goods are confirmed back at the branch. If the return itself can't be completed, the order becomesManualReviewRequired(Section 8.2) and needs a human — on FleetBridge's or your tenant's side — to sort it out. - Subscribe to return webhooks:
delivery.return_requested,delivery.returning_to_origin,delivery.returned_to_origin,delivery.return_failed(Section 9.7) keep you posted in real time without polling. - Re-delivery is a new order. FleetBridge won't automatically re-attempt delivery of returned goods. If your business needs a second delivery attempt after a return, create a new order for it once the original is resolved.
Don't advertise automated return handling to your own end users based on this integration. "FleetBridge notifies us and our operations team follows up" is the honest description of what happens today — stick to that.
19. Branch / pickup resolution
Create resolves the delivery's origin branch in this priority order:
branchId, if supplied — must resolve to an active branch belonging to your tenant, or404 BRANCH_NOT_FOUND.- Else
externalBranchId, if supplied and non-blank — same active-branch requirement. - Else nearest match by
pickup.lat/pickup.lng— FleetBridge finds the closest active branch whose configured match radius (a per-branch setting, 100 meters by default) contains your supplied pickup coordinates. If no active branch is within its own radius of the supplied point,404 BRANCH_NOT_FOUND(withpickupLat/pickupLngechoed indetails).
If you already know your FleetBridge branchId — most integrations will, once set up — send it. It's the fastest, least ambiguous path. externalBranchId is for integrations that track their own store/branch codes instead. The coordinate-based fallback exists for integrations that only know a physical location, not a code, but it's inherently less precise (a pickup point sitting exactly between two branches' radii is genuinely ambiguous). Avoid leaning on it as your primary mechanism if you can help it.
20. Environments
FleetBridge doesn't publish one fixed hostname for every customer. As part of onboarding you get:
- A staging Base URL and staging
X-Api-Key, for development and certification (Section 23). - A production Base URL and production
X-Api-Key, issued at activation.
There's no way to tell "which environment" a key belongs to from its format (Section 2.2) — the Base URL you point at is what determines that. Keep staging and production credentials in clearly separate configuration in your own systems. FleetBridge can't protect you from accidentally pointing a production key at a staging URL, or the reverse.
21. Versioning
- API major version:
v1, in every path (/api/v1/...). A breaking change (wire format, authentication, signature algorithm, a required field, or a status/event semantic change) would require a new major version and a distinct migration path — it would never be silently applied tov1. - This document's revision:
1.1.0, tracked in the Changelog (CHANGELOG.md) alongside this package. - Additive changes (a new optional field, a new event type, a new enum value in a non-exhaustively-matched position) may ship within
v1without notice beyond the changelog. Write your JSON parsing to ignore unknown fields (Section 6) and your event-type handling to tolerate an event type you don't recognize yet (skip it, don't crash), so additive changes never break your integration. - Removing or renaming a field, changing a field's type, or changing the meaning of an existing status/event is a breaking change and would ship as a new API major version with its own contract document, never silently inside
v1.
22. Rate limits
There's currently one rate limit on Order Source traffic, and it's intentionally coarse. We're documenting it honestly here rather than implying some business-level quota that doesn't actually exist:
- 300 requests per minute, per source IP address, applied to *any* request carrying an
X-Api-Keyheader. Not specific to order creation, not scoped per API key, not configurable per tenant. It exists purely to bound abusive traffic before it reaches authentication, not as a fair-use business quota. - On rejection:
429 Too Many Requests, aRetry-Afterheader (seconds), and the standard error envelope:
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/problem+json{
"status": 429,
"title": "Too Many Requests",
"detail": "Too many requests carrying an API key from this address. Please try again later.",
"errorCode": "RATE_LIMIT_EXCEEDED",
"correlationId": "..."
}Respect Retry-After instead of guessing your own backoff. If you're behind a shared outbound IP — a NAT gateway, a shared hosting provider — remember this limit is IP-scoped, not key-scoped, and plan capacity with that in mind. There's no separate, higher, per-tenant business quota to request right now. If your real traffic needs exceed this ceiling, talk to FleetBridge directly rather than architecting around a quota that isn't actually part of the contract.
Retrying a rate-limited Create call is always safe if you reuse the same Idempotency-Key (Section 13).
23. Integration checklist
Before development
- Staging
X-Api-Keyand staging Base URL received. - Your callback URL is reachable over HTTPS from the public internet.
- Webhook endpoint registered by FleetBridge and your webhook signing secret captured and stored securely (Section 9.2, 10.2).
- You understand the idempotency-replay semantics in Section 13.3 before writing any retry logic.
Development
- Authentication works — a valid Create request returns
201with the expected shape. - Create works for both immediate and scheduled orders.
- Idempotent replay proven: same
Idempotency-Key, same body, twice → sameplatformOrderIdboth times. - Update works, and you've confirmed a field's
NotApplicable/NotSupportedByProvider/PropagationFailedresult doesn't crash your handling. - Cancel works for at least the "before dispatch" case; you understand the
CANCELLATION_NOT_SUPPORTED_AT_STAGEcase can legitimately happen. -
GET .../status,.../tracking,.../tracking-historyall work and null-safe your parsing (most tracking fields are nullable). - Webhook signature verification implemented and tested against
POST /api/v1/webhooks/test(Section 9.2), using the raw request body (Section 10.4). - Your webhook handler deduplicates on
eventIdand tolerates out-of-order delivery (Section 9.5).
Staging certification (Section 24)
- Duplicate Create (same
Idempotency-Key) returns the original order, not a new one. - Create with the same
Idempotency-Keybut a different body still returns the original, unchanged — confirms you are not relying on a "conflict" error that does not exist. - A scheduled order validates the minimum lead time and dispatches around the expected time.
- An invalid request (bad coordinates, bad enum, missing required field) returns the expected
400+errorCode. - Cancellation at each reachable stage behaves as documented in Section 12.1.
- A webhook delivery failure (temporarily break your own endpoint) is retried per the schedule in Section 9.4, and you can observe/request a manual resend through FleetBridge if needed.
- Duplicate webhook delivery does not double-process on your end.
- If your staging environment lets you exercise a failover scenario, confirm you continue correlating correctly on
platformOrderIdacross a provider change (Section 15.3).
Production activation
- Production
X-Api-Keyand production Base URL configured, kept separate from staging (Section 20). - Production callback URL registered and its own webhook secret captured.
- You have a documented process for what happens if/when FleetBridge needs to rotate your webhook secret (Section 9.10 — you have a 24-hour overlap window, not zero downtime, if you react promptly).
- You know who to contact at FleetBridge for integration issues, and you log
correlationIdfrom error responses so a support conversation can reference a specific failed request.
24. Certification / self-test
Check certification/README.md in this package for a runnable checklist and script (certification/certify.py) that exercises this whole contract — Create, idempotent replay, Update, Cancel, validation errors, and optionally webhook signature verification against a local receiver — using your own staging credentials. No access to FleetBridge's source code or infrastructure required; it just calls the public HTTP contract described in this document, and prints a pass/fail report per checklist item plus a machine-readable JSON result file you can attach to a certification request.
25. Changelog
See CHANGELOG.md in this package.