FBFleetBridge Provider APIImplementation guide
Standard Contract v1.2.0

Provider-facing API specification

One contract. Every delivery event.

Build, test, and certify a delivery provider integration with complete payload, authentication, and webhook examples.

API majorv1
Contract1.2.0
Revision2026-10-10
FormatJSON over HTTPS
No matching section

Try authentication, webhook, status, or capability.

01

Quick start

FleetBridge calls your provider API. Your provider sends signed lifecycle events to the callback URL included with each order.

Expose stagingProvide a public HTTPS base URL and staging API key.
Accept deliveryImplement POST /deliveries with durable idempotency.
Send eventsStore the callback URL and sign the exact body.
CertifyUse generated orders to validate capabilities.

Minimum working request

cURL
curl --request POST 'https://staging.provider.example/fleetbridge/v1/deliveries' \
  --header 'Authorization: Bearer YOUR_STAGING_API_KEY' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Accept: application/json' \
  --data-raw '{
    "platformReference": "IFB-TEST-20260921-7f2c48",
    "idempotencyKey": "IFB-TEST-20260921-7f2c48",
    "pickupAddress": "King Fahd Road, Al Olaya, Riyadh",
    "pickupLat": 24.7112,
    "pickupLng": 46.6744,
    "customerName": "FleetBridge Test Customer",
    "customerPhone": "+966500000000",
    "dropoffAddress": "Prince Turki Street, Al Malqa, Riyadh",
    "dropoffLat": 24.8064,
    "dropoffLng": 46.6172,
    "paymentMethod": "cash",
    "amount": 241.00,
    "deliveryFeeAmount": 18.50,
    "currency": "SAR",
    "notes": "Test order only. Do not dispatch as a real delivery.",
    "orderReference": "ORD-20260921-1001",
    "preparationTimeMinutes": 15,
    "scheduledDeliveryAtUtc": null,
    "webhook": {"url": "https://api.fleetbridge.example/api/v1/webhooks/providers/REDACTED_CONNECTION_TOKEN"}
  }'
200 OK
{
  "accepted": true,
  "providerDeliveryId": "DLV-20260921-18472",
  "providerTrackingId": "TRK-RUH-883104",
  "rejectionReason": null
}
Assignment can be the acceptance

If a valid driver.assigned arrives before delivery.accepted, FleetBridge treats it as implicit acceptance and prevents timeout routing to another provider.

02

Integration model

The two traffic directions use different credentials. Do not reuse one for the other.

FleetBridge to provider

Tenant-specific credential.

Header: Authorization: Bearer <API_KEY>

Create, update, cancel, return, status, tracking, and connection test.

Provider to FleetBridge

Provider-wide signing secret plus connection-specific callback URL.

Header: X-Platform-Signature

Acceptance, assignment, location, ETA, pickup, delivery, cancellation, and failure.

Standard and custom contracts

ModeUse whenBehavior
StandardProvider implements this API.Fixed paths, payloads, statuses, Bearer auth, and webhook shape.
CustomExisting provider API needs mapping.Platform Admin configures nested fields. Tenant users enter named credentials, never raw JSON.
No custom JSONDefinition is empty or unavailable.FleetBridge uses Standard Contract as the safe default.
Bearer in a custom contract

Define an apiKey credential, map it to Authorization, and format it as Bearer {apiKey}. Store only the raw token. Do not ask the tenant user to type Bearer.

Callback token and webhook secret

  • The callback URL token routes one tenant and provider connection. It is confidential.
  • The HMAC secret proves body authenticity and integrity. It is a different value.
  • The webhook secret is global for the provider catalog entry across all tenants.
  • Only Platform Admin generates or rotates it. The raw secret is shown once.
  • Tenant users never create, view, or rotate the provider-wide secret.
  • Neither secret belongs inside the delivery JSON body.
03

Authentication

Every FleetBridge request to the provider includes a Bearer token.

HTTP headers
Authorization: Bearer YOUR_PROVIDER_API_KEY
Content-Type: application/json; charset=utf-8
Accept: application/json
The space after Bearer is required

Use the literal word Bearer, one space, then the raw API key. Do not put the key in the URL or JSON body.

cURL connection test
Shell
curl --request POST 'https://staging.provider.example/fleetbridge/v1/webhooks/test' \
  --header 'Authorization: Bearer YOUR_STAGING_API_KEY' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Accept: application/json' \
  --data-raw '{}'
JavaScript fetch
JavaScript
const response = await fetch(
  "https://staging.provider.example/fleetbridge/v1/webhooks/test",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FLEETBRIDGE_PROVIDER_API_KEY}`,
      "Content-Type": "application/json; charset=utf-8",
      Accept: "application/json"
    },
    body: JSON.stringify({})
  }
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
C# HttpClient
C#
using System.Net.Http.Headers;
using System.Net.Http.Json;

var client = new HttpClient {
    BaseAddress = new Uri("https://staging.provider.example/fleetbridge/v1/")
};
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);
var response = await client.PostAsJsonAsync("webhooks/test", new { });
response.EnsureSuccessStatusCode();
Python requests
Python
import os, requests

response = requests.post(
    "https://staging.provider.example/fleetbridge/v1/webhooks/test",
    headers={"Authorization": f"Bearer {os.environ['FLEETBRIDGE_PROVIDER_API_KEY']}"},
    json={}, timeout=15
)
response.raise_for_status()

Return 401 for a missing, malformed, expired, or invalid token. Return 403 when the token is valid but not authorized for the account or delivery. A connection test returning 403 has reached the provider but has failed authorization.

04

Endpoint reference

Expose these paths below the configured HTTPS base URL. FleetBridge does not follow redirects.

POST/deliveriesCreate. Retried with same idempotency key.
GET/deliveries/{providerDeliveryId}/statusCurrent state. Safe to retry.
GET/deliveries/{providerDeliveryId}/trackingDriver, location, tracking URL, and ETA.
PATCH/deliveries/{providerDeliveryId}Update supported fields. No transparent retry.
POST/deliveries/{providerDeliveryId}/cancelCancel at the stated stage.
POST/deliveries/{providerDeliveryId}/returnReturn to origin when certified.
POST/webhooks/testValidate URL and Bearer authentication.
Transport

Use public TLS, respond within 15 seconds, keep bodies below 5 MiB, and return application/json; charset=utf-8.

05

Create delivery

POST /deliveries records one delivery and returns durable provider identifiers.

Rich request

POST /deliveries
{
  "platformReference": "IFB-TEST-20260921-7f2c48",
  "idempotencyKey": "IFB-TEST-20260921-7f2c48",
  "pickupAddress": "Cervo Kitchen, King Fahd Road, Al Olaya, Riyadh",
  "pickupLat": 24.711219,
  "pickupLng": 46.674427,
  "customerName": "FleetBridge Test Customer",
  "customerPhone": "+966500000000",
  "dropoffAddress": "Building 214, Prince Turki Street, Al Malqa, Riyadh",
  "dropoffLat": 24.806435,
  "dropoffLng": 46.617284,
  "paymentMethod": "cash",
  "amount": 241.00,
  "deliveryFeeAmount": 18.50,
  "currency": "SAR",
  "notes": "Gate B. Call on arrival. Staging test only.",
  "orderReference": "ORD-20260921-1001",
  "preparationTimeMinutes": 15,
  "scheduledDeliveryAtUtc": "2026-09-21T18:30:00Z",
  "webhook": {
    "url": "https://api.fleetbridge.example/api/v1/webhooks/providers/REDACTED_CONNECTION_TOKEN"
  }
}
FieldTypeRequiredRule
platformReferencestringYesStable correlation, max 200. Echo unchanged.
idempotencyKeystringYesMax 200. Currently equals platformReference.
pickupAddress, dropoffAddressstringYesMax 500 each.
pickupLat/Lng, dropoffLat/LngnumberYesLatitude -90..90; longitude -180..180.
customerNamestringYesMax 200.
customerPhonestringYesMax 50; preserve leading plus.
paymentMethodstringYescash, card, online, wallet, or agreed value, max 100.
amountnumberYes0..9,999,999,999.99, up to two decimals.
deliveryFeeAmountnumber/nullNoSame money range.
currencystringYesThree uppercase letters, such as SAR.
notesstring/nullNoMax 2,000.
orderReferencestring/nullNoMax 200. Human-readable order number for display only. Not unique. Never use for correlation, lookup, or idempotency. Accept and ignore it if unused.
preparationTimeMinutesintegerYesZero or greater.
scheduledDeliveryAtUtcdate-time/nullNoRFC 3339. Requires capability.
webhook.urlHTTPS URINoImmutable callback, max 2,048.

Accepted

200 OK
{
  "accepted": true,
  "providerDeliveryId": "DLV-20260921-18472",
  "providerTrackingId": "TRK-RUH-883104",
  "rejectionReason": null
}

Business rejection

200 OK
{
  "accepted": false,
  "providerDeliveryId": null,
  "providerTrackingId": null,
  "rejectionReason": "outside_service_area"
}
Accepted requires an ID

When accepted is true, providerDeliveryId must be nonblank.

Idempotency

  1. Create at most one physical delivery for the first valid key.
  2. Identical, concurrent, and post-restart replays return the original identifiers.
  3. Changed content or callback URL with the same key returns 409.
  4. A replay that differs only in orderReference, including present versus omitted, should be treated as compatible.
  5. If a replay omits the callback, retain the callback from the first request.
  6. Never create a second delivery after a timeout or ambiguous response.
06

Update, cancel, and return

Update

PATCH /deliveries/{providerDeliveryId} accepts any supported subset. Send dropoff coordinates together. Omitted and explicit null both mean leave unchanged in v1.1.

PATCH request
{
  "dropoffAddress": "Unit 8, Anas Bin Malik Road, Riyadh",
  "dropoffLat": 24.83072,
  "dropoffLng": 46.63118,
  "customerPhone": "+966500000001",
  "scheduledDeliveryAtUtc": "2026-09-21T19:00:00Z",
  "notes": "Use north entrance.",
  "customerName": "FleetBridge Updated Customer",
  "customerEmail": "test.customer@example.invalid",
  "amount": 252.50,
  "currency": "SAR",
  "paymentMethod": "card",
  "deliveryFeeAmount": 20.00,
  "preparationTimeMinutes": 20
}
200 OK
{
  "fieldAccepted": {
    "dropoffAddress": true,
    "dropoffLat": true,
    "dropoffLng": true,
    "customerPhone": true,
    "scheduledDeliveryAtUtc": true,
    "notes": true,
    "customerName": true,
    "customerEmail": true,
    "amount": true,
    "currency": true,
    "paymentMethod": true,
    "deliveryFeeAmount": true,
    "preparationTimeMinutes": true
  },
  "errorMessage": null
}

Return one Boolean for each submitted field. Use 422 or false for unsupported values. Never report success and discard data.

Cancel

POST /deliveries/{id}/cancel
{"stage":"before_pickup"}
200 OK
{"confirmed":true,"errorMessage":null}

Stage is before_pickup or after_pickup. Repeated cancellation must be safe.

Return to origin

POST /deliveries/{id}/return
{"reasonCode":"customer_unavailable"}
200 OK
{"accepted":true,"errorMessage":null}

Use only when supportsReturnToOrigin is enabled and certified.

07

Status and tracking

Webhook and polling results must converge on the same state.

sent_to_providerRecorded
provider_acceptedAccepted
driver_assignedAssigned
arrived_at_pickupAt pickup
picked_upCollected
on_the_wayTo customer
deliveredTerminal
cancelledTerminal
failedTerminal failure
return_requestedRequested
returning_to_originReturning
returned_to_originTerminal
return_failedNeeds review

Status response

GET .../status
{
  "status": "on_the_way",
  "eventTimeUtc": "2026-09-21T17:42:18Z"
}

Tracking response

GET .../tracking
{
  "driverName": "Omar A.",
  "driverPhone": "+966500000099",
  "driverLat": 24.763281,
  "driverLng": 46.646412,
  "trackingUrl": "https://tracking.provider.example/TRK-RUH-883104",
  "estimatedDeliveryAtUtc": "2026-09-21T18:06:00Z",
  "eventTimeUtc": "2026-09-21T17:42:18Z"
}
  • Return 404 only when delivery is genuinely unknown.
  • Do not hide timeout, rate limit, or dependency failure as 404.
  • Do not map an unknown internal state to failed.
  • Return null for unavailable tracking data. Never invent values.
08

Webhook events

Post events to the exact callback stored with the delivery. Always echo platformReference.

eventTypeStatusExtra data
delivery.acceptedprovider_acceptedProvider ID
driver.assigneddriver_assignedAvailable driver identity
driver.location_updatedCurrent nonterminaldriverLat and driverLng
eta.updatedCurrent nonterminalestimatedDeliveryAtUtc
tracking.updatedCurrentURL or tracking fields
delivery.picked_uppicked_upNone
delivery.delivereddeliveredNone
delivery.cancelledcancelledNone
delivery.failedfailedReal terminal failure

Driver assigned

POST callback URL
{
  "eventType": "driver.assigned",
  "platformReference": "IFB-TEST-20260921-7f2c48",
  "providerDeliveryId": "DLV-20260921-18472",
  "providerTrackingId": "TRK-RUH-883104",
  "status": "driver_assigned",
  "eventTimeUtc": "2026-09-21T17:31:42Z",
  "driverName": "Omar A.",
  "driverPhone": "+966500000099",
  "driverLat": null,
  "driverLng": null,
  "trackingUrl": "https://tracking.provider.example/TRK-RUH-883104",
  "estimatedDeliveryAtUtc": "2026-09-21T18:06:00Z"
}
Implicit acceptance

If this is the first valid event, FleetBridge creates the winning shipment at driver_assigned, associates the provider IDs, and stops timeout failover.

Location update

driver.location_updated
{
  "eventType": "driver.location_updated",
  "platformReference": "IFB-TEST-20260921-7f2c48",
  "providerDeliveryId": "DLV-20260921-18472",
  "providerTrackingId": "TRK-RUH-883104",
  "status": "on_the_way",
  "eventTimeUtc": "2026-09-21T17:42:18Z",
  "driverName": "Omar A.",
  "driverPhone": "+966500000099",
  "driverLat": 24.763281,
  "driverLng": 46.646412,
  "trackingUrl": "https://tracking.provider.example/TRK-RUH-883104",
  "estimatedDeliveryAtUtc": "2026-09-21T18:06:00Z"
}

Delivered

delivery.delivered
{
  "eventType": "delivery.delivered",
  "platformReference": "IFB-TEST-20260921-7f2c48",
  "providerDeliveryId": "DLV-20260921-18472",
  "providerTrackingId": "TRK-RUH-883104",
  "status": "delivered",
  "eventTimeUtc": "2026-09-21T18:02:51Z",
  "driverName": "Omar A.",
  "driverPhone": null,
  "driverLat": null,
  "driverLng": null,
  "trackingUrl": "https://tracking.provider.example/TRK-RUH-883104",
  "estimatedDeliveryAtUtc": null
}
  • platformReference, status, and eventTimeUtc are required.
  • New v1.1 integrations send eventType.
  • Keep original event time when retrying the same logical event.
  • Duplicates and out-of-order events must be safe. FleetBridge ignores stale regressions.
  • Tracking values use their own event time for freshness.
  • Stop nonterminal events after a terminal event.
  • FleetBridge resolves tenant from the correlated record, not webhook body data.
09

Webhook signing

Sign the exact UTF-8 request body using HMAC-SHA256 and the global provider webhook secret.

Headers
Content-Type: application/json; charset=utf-8
X-Platform-Signature: LOWERCASE_HEX_HMAC_SHA256
No prefix

Use lowercase hexadecimal only. Do not add Bearer or sha256=. Sign the bytes you send, not a re-serialized object.

Fixed test vector

Secrettest-secret
Exact body{"status":"delivered"}
Signaturebfebae765b7f20464b4b64d37314fc073a178a293762aaf32920be724d5fde18

JavaScript

Node.js
import { createHmac } from "node:crypto";

const event = {
  eventType: "driver.assigned",
  platformReference: "IFB-TEST-20260921-7f2c48",
  providerDeliveryId: "DLV-20260921-18472",
  providerTrackingId: "TRK-RUH-883104",
  status: "driver_assigned",
  eventTimeUtc: "2026-09-21T17:31:42Z",
  driverName: "Omar A.", driverPhone: "+966500000099",
  driverLat: null, driverLng: null,
  trackingUrl: "https://tracking.provider.example/TRK-RUH-883104",
  estimatedDeliveryAtUtc: "2026-09-21T18:06:00Z"
};
const rawBody = JSON.stringify(event);
const signature = createHmac("sha256", process.env.FLEETBRIDGE_WEBHOOK_SECRET)
  .update(Buffer.from(rawBody, "utf8")).digest("hex");

const response = await fetch(process.env.FLEETBRIDGE_CALLBACK_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json; charset=utf-8",
    "X-Platform-Signature": signature
  },
  body: rawBody
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);

C#

.NET
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

var payload = new {
    eventType = "driver.assigned",
    platformReference = "IFB-TEST-20260921-7f2c48",
    providerDeliveryId = "DLV-20260921-18472",
    providerTrackingId = "TRK-RUH-883104",
    status = "driver_assigned",
    eventTimeUtc = "2026-09-21T17:31:42Z",
    driverName = "Omar A.",
    driverPhone = "+966500000099",
    driverLat = (double?)null,
    driverLng = (double?)null,
    trackingUrl = "https://tracking.provider.example/TRK-RUH-883104",
    estimatedDeliveryAtUtc = "2026-09-21T18:06:00Z"
};
var rawBody = JsonSerializer.Serialize(payload);
var signature = Convert.ToHexString(HMACSHA256.HashData(
    Encoding.UTF8.GetBytes(webhookSecret),
    Encoding.UTF8.GetBytes(rawBody)
)).ToLowerInvariant();

using var request = new HttpRequestMessage(HttpMethod.Post, callbackUrl);
request.Headers.TryAddWithoutValidation("X-Platform-Signature", signature);
request.Content = new StringContent(rawBody, Encoding.UTF8, "application/json");
using var response = await httpClient.SendAsync(request);
response.EnsureSuccessStatusCode();

Python

Python
import hashlib, hmac, json, os, requests

event = {
    "eventType": "driver.assigned",
    "platformReference": "IFB-TEST-20260921-7f2c48",
    "providerDeliveryId": "DLV-20260921-18472",
    "providerTrackingId": "TRK-RUH-883104",
    "status": "driver_assigned",
    "eventTimeUtc": "2026-09-21T17:31:42Z",
    "driverName": "Omar A.",
    "driverPhone": "+966500000099",
    "driverLat": None,
    "driverLng": None,
    "trackingUrl": "https://tracking.provider.example/TRK-RUH-883104",
    "estimatedDeliveryAtUtc": "2026-09-21T18:06:00Z",
}
raw_body = json.dumps(event, separators=(",", ":"), ensure_ascii=False)
body_bytes = raw_body.encode("utf-8")
signature = hmac.new(
    os.environ["FLEETBRIDGE_WEBHOOK_SECRET"].encode("utf-8"),
    body_bytes, hashlib.sha256
).hexdigest()

response = requests.post(
    os.environ["FLEETBRIDGE_CALLBACK_URL"], data=body_bytes,
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "X-Platform-Signature": signature,
    }, timeout=15
)
response.raise_for_status()
10

Reliability and convergence

FleetBridge operationAutomatic retryWhy
CreateUp to 3 total attemptsSame idempotency key
Status, tracking, testUp to 3 total attemptsSafe operation
Update, cancel, returnNo transparent retryOutcome may be ambiguous

FleetBridge retries after network failure, timeout, 429, or 5xx. It honors Retry-After up to 30 seconds.

Provider callback retry

  • Any 2xx completes the attempt.
  • Retry 408, 429, and 5xx.
  • Do not retry other 4xx until configuration or payload is corrected.
  • Use bounded exponential backoff with jitter for at least six attempts across at least 15 minutes.
  • Honor Retry-After.
Timeout means unknown outcome

On Create timeout, return the original delivery for the repeated identity. Never create a second physical delivery.

FleetBridge may poll while webhooks are active. Both paths use the same transition and tenant-safe correlation pipeline.

11

Capabilities

Declare only working behavior that passes generated tests.

CapabilityMeaningEvidence
supportsWebhookSigned lifecycle eventsSignature, retry, duplicate, routing
supportsPollingStatus convergesLifecycle and unknown delivery
supportsTrackingUrlUsable tracking URLTracking response
supportsDriverLocationDriver coordinatesTracking and location event
supportsEtaDelivery ETATracking and ETA event
supportsProofOfDeliveryProof artifactMust be false in v1.1
supportsExternalReferencePersists platformReferenceCreate and every event
supportsIdempotencyKeyDurable idempotencyReplay, conflict, concurrency, restart
supportsCancellationBeforePickupEarly cancellationControlled test
supportsCancellationAfterPickupLate cancellationControlled test
supportsOrderUpdateGeneral updatesField-by-field PATCH
supportsAddressUpdateDestination updatePATCH
supportsPhoneUpdatePhone updatePATCH
supportsScheduledDeliveryScheduled createScheduled fixture
supportsScheduledDeliveryUpdateSchedule changesPATCH
supportsReturnToOriginReturn endpointControlled return
Minimum transport

A provider supports at least one of webhook or polling. A stub or roadmap item is not a capability.

12

Errors and rate limits

Error envelope
{
  "code": "validation_failed",
  "message": "Request validation failed.",
  "retryable": false,
  "fieldErrors": {
    "currency": ["Must be three uppercase characters."],
    "dropoffLat": ["Must be between -90 and 90."]
  }
}
HTTPMeaningAction
400Malformed requestCorrect request
401Missing or invalid tokenCorrect credentials
403Valid token lacks accessCorrect authorization
404Unknown deliveryDo not retry
409Idempotency, callback, or state conflictReconcile
422Invalid or unsupported valuesCorrect payload
429Rate limitedRetry using Retry-After
500Unexpected failureRetry safe operations
502/503Transient unavailable dependencyRetry safe operations
429 example
HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 30

{"code":"rate_limit","message":"Rate limit exceeded.","retryable":true}

Never expose stack traces, SQL, exception class names, credentials, callback tokens, or webhook secrets.

13

Testing and certification

FleetBridge generates safe test data, runs supported operations, and recommends capabilities from observed results.

Connection test

FleetBridge sends POST /webhooks/test with Bearer authentication and {}. This tests reachability and authorization only. A 401 or 403 fails the test.

Request
POST /fleetbridge/v1/webhooks/test HTTP/1.1
Host: staging.provider.example
Authorization: Bearer YOUR_STAGING_API_KEY
Content-Type: application/json; charset=utf-8
Accept: application/json

{}

Generated test flow

  1. Platform Admin saves base URL and named credentials.
  2. FleetBridge generates a unique IFB-TEST reference and safe customer, address, and amount.
  3. Connection verifies TLS, URL, endpoint, and Bearer token.
  4. Create validates the rich payload, idempotency, and provider IDs.
  5. Webhook and polling verify lifecycle convergence and correlation.
  6. Update, cancel, tracking, and return run only when requested.
  7. FleetBridge returns pass, fail, skipped, and recommended capability values.

Example result

Sanitized certification result
{
  "testReference": "IFB-TEST-202609211705-7f2c48",
  "generatedAtUtc": "2026-09-21T17:05:42Z",
  "sampleCustomerName": "FleetBridge Test Customer",
  "sampleCustomerPhone": "+966500000000",
  "sampleDropoffAddress": "FleetBridge Test District, Riyadh",
  "checks": [
    {"key":"connection","status":"passed","messageCode":"connectionPassed","capabilityKey":null,"detail":"HTTP 200 OK"},
    {"key":"webhook","status":"passed","messageCode":"signedWebhookReceived","capabilityKey":"supportsWebhook","detail":"driver.assigned correlated"},
    {"key":"statusPolling","status":"passed","messageCode":"pollingConverged","capabilityKey":"supportsPolling","detail":"driver_assigned"},
    {"key":"trackingUrl","status":"passed","messageCode":"trackingUrlReturned","capabilityKey":"supportsTrackingUrl","detail":"HTTPS URL received"},
    {"key":"cancelBeforePickup","status":"passed","messageCode":"cancellationConfirmed","capabilityKey":"supportsCancellationBeforePickup","detail":null}
  ],
  "recommendedCapabilities": {
    "supportsWebhook": true,
    "supportsPolling": true,
    "supportsTrackingUrl": true,
    "supportsDriverLocation": true,
    "supportsEta": true,
    "supportsProofOfDelivery": false,
    "supportsExternalReference": true,
    "supportsIdempotencyKey": true,
    "supportsCancellationBeforePickup": true,
    "supportsCancellationAfterPickup": false,
    "supportsOrderUpdate": true,
    "supportsAddressUpdate": true,
    "supportsPhoneUpdate": true,
    "supportsScheduledDelivery": true,
    "supportsScheduledDeliveryUpdate": true,
    "supportsReturnToOrigin": false
  }
}

End-to-end route test

In Delivery workspace, select a branch and generate a test order without selecting a provider. FleetBridge uses real routing rules and shows attempts, shipment status, callbacks, polling, and logs under one reference.

Test traffic is operational traffic

Recognize staging credentials and IFB-TEST references. Never dispatch a generated test to a real courier or customer.

Certification lifecycle
IMPLEMENTATION_DECLARED
  -> STAGING_CONFIGURED
  -> STAGING_CERTIFIED
  -> PRODUCTION_CONFIGURED
  -> PRODUCTION_CERTIFIED

Administrative states: SUSPENDED, RECERTIFICATION_REQUIRED
14

Security and launch checklist

  • Publicly trusted HTTPS certificate
  • Separate staging and production URLs and keys
  • Scoped and revocable Bearer tokens
  • Global HMAC secret in secret manager
  • Callback tokens redacted from logs
  • Signature covers exact body bytes
  • Correct 401 and 403 behavior
  • Partner and account data isolation
  • Minimum personal data and retention
  • Durable multi-instance idempotency
  • Unknown delivery cannot leak another tenant
  • Safe callback URL validation and no redirects
  • 429 includes valid Retry-After
  • Every enabled capability has evidence
  • Proof of delivery disabled in v1.1
  • Production activation approved separately
15

Release notes and compatibility

Operational clarifications, 2026-09-21

  • The webhook signing secret is provider-wide, managed by Platform Admin, and shared across tenant connections.
  • driver.assigned is implicit acceptance when it is the first valid provider event.
  • Standard Contract is the fallback when custom contract JSON is absent.
  • Custom Bearer mapping stores the raw token and generates the Authorization header.

Version 1.2.0, contract revision 2026-10-10

  • Optional Create Delivery orderReference: human-readable order number for display only. Never a correlation, lookup, or idempotency key; not echoed in events, status, or tracking; not updatable. Providers that do not display it accept and ignore it.

Version 1.1.0, contract revision 2026-09-19

  • Immutable per-delivery callback and multi-brand isolation.
  • Nine standard webhook event types.
  • Driver location, ETA, retry, ordering, and timeout rules.
  • Complete error, 429, Retry-After, and replay behavior.
  • Proof of delivery remains unavailable.

Compatibility

New optional fields, optional events, examples, and clarifications are backward-compatible. Removing or renaming fields, changing required fields, authentication, signatures, status meaning, or endpoint behavior requires a new API major and recertification.

Normative terms

MUST and MUST NOT are mandatory. SHOULD is recommended unless a documented reason applies. MAY is optional.