FleetBridge to provider
Tenant-specific credential.
Header: Authorization: Bearer <API_KEY>
Create, update, cancel, return, status, tracking, and connection test.
Provider-facing API specification
Build, test, and certify a delivery provider integration with complete payload, authentication, and webhook examples.
Try authentication, webhook, status, or capability.
FleetBridge calls your provider API. Your provider sends signed lifecycle events to the callback URL included with each order.
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"}
}'{
"accepted": true,
"providerDeliveryId": "DLV-20260921-18472",
"providerTrackingId": "TRK-RUH-883104",
"rejectionReason": null
}If a valid driver.assigned arrives before delivery.accepted, FleetBridge treats it as implicit acceptance and prevents timeout routing to another provider.
The two traffic directions use different credentials. Do not reuse one for the other.
Tenant-specific credential.
Header: Authorization: Bearer <API_KEY>
Create, update, cancel, return, status, tracking, and connection test.
Provider-wide signing secret plus connection-specific callback URL.
Header: X-Platform-Signature
Acceptance, assignment, location, ETA, pickup, delivery, cancellation, and failure.
| Mode | Use when | Behavior |
|---|---|---|
| Standard | Provider implements this API. | Fixed paths, payloads, statuses, Bearer auth, and webhook shape. |
| Custom | Existing provider API needs mapping. | Platform Admin configures nested fields. Tenant users enter named credentials, never raw JSON. |
| No custom JSON | Definition is empty or unavailable. | FleetBridge uses Standard Contract as the safe default. |
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.
Every FleetBridge request to the provider includes a Bearer token.
Authorization: Bearer YOUR_PROVIDER_API_KEY
Content-Type: application/json; charset=utf-8
Accept: application/jsonUse the literal word Bearer, one space, then the raw API key. Do not put the key in the URL or JSON body.
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 '{}'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}`);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();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.
Expose these paths below the configured HTTPS base URL. FleetBridge does not follow redirects.
/deliveriesCreate. Retried with same idempotency key./deliveries/{providerDeliveryId}/statusCurrent state. Safe to retry./deliveries/{providerDeliveryId}/trackingDriver, location, tracking URL, and ETA./deliveries/{providerDeliveryId}Update supported fields. No transparent retry./deliveries/{providerDeliveryId}/cancelCancel at the stated stage./deliveries/{providerDeliveryId}/returnReturn to origin when certified./webhooks/testValidate URL and Bearer authentication.Use public TLS, respond within 15 seconds, keep bodies below 5 MiB, and return application/json; charset=utf-8.
POST /deliveries records one delivery and returns durable provider identifiers.
{
"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"
}
}| Field | Type | Required | Rule |
|---|---|---|---|
platformReference | string | Yes | Stable correlation, max 200. Echo unchanged. |
idempotencyKey | string | Yes | Max 200. Currently equals platformReference. |
pickupAddress, dropoffAddress | string | Yes | Max 500 each. |
pickupLat/Lng, dropoffLat/Lng | number | Yes | Latitude -90..90; longitude -180..180. |
customerName | string | Yes | Max 200. |
customerPhone | string | Yes | Max 50; preserve leading plus. |
paymentMethod | string | Yes | cash, card, online, wallet, or agreed value, max 100. |
amount | number | Yes | 0..9,999,999,999.99, up to two decimals. |
deliveryFeeAmount | number/null | No | Same money range. |
currency | string | Yes | Three uppercase letters, such as SAR. |
notes | string/null | No | Max 2,000. |
orderReference | string/null | No | Max 200. Human-readable order number for display only. Not unique. Never use for correlation, lookup, or idempotency. Accept and ignore it if unused. |
preparationTimeMinutes | integer | Yes | Zero or greater. |
scheduledDeliveryAtUtc | date-time/null | No | RFC 3339. Requires capability. |
webhook.url | HTTPS URI | No | Immutable callback, max 2,048. |
{
"accepted": true,
"providerDeliveryId": "DLV-20260921-18472",
"providerTrackingId": "TRK-RUH-883104",
"rejectionReason": null
}{
"accepted": false,
"providerDeliveryId": null,
"providerTrackingId": null,
"rejectionReason": "outside_service_area"
}When accepted is true, providerDeliveryId must be nonblank.
409.orderReference, including present versus omitted, should be treated as compatible.PATCH /deliveries/{providerDeliveryId} accepts any supported subset. Send dropoff coordinates together. Omitted and explicit null both mean leave unchanged in v1.1.
{
"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
}{
"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.
{"stage":"before_pickup"}{"confirmed":true,"errorMessage":null}Stage is before_pickup or after_pickup. Repeated cancellation must be safe.
{"reasonCode":"customer_unavailable"}{"accepted":true,"errorMessage":null}Use only when supportsReturnToOrigin is enabled and certified.
Webhook and polling results must converge on the same state.
{
"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",
"eventTimeUtc": "2026-09-21T17:42:18Z"
}failed.Post events to the exact callback stored with the delivery. Always echo platformReference.
| eventType | Status | Extra data |
|---|---|---|
delivery.accepted | provider_accepted | Provider ID |
driver.assigned | driver_assigned | Available driver identity |
driver.location_updated | Current nonterminal | driverLat and driverLng |
eta.updated | Current nonterminal | estimatedDeliveryAtUtc |
tracking.updated | Current | URL or tracking fields |
delivery.picked_up | picked_up | None |
delivery.delivered | delivered | None |
delivery.cancelled | cancelled | None |
delivery.failed | failed | Real terminal failure |
{
"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"
}If this is the first valid event, FleetBridge creates the winning shipment at driver_assigned, associates the provider IDs, and stops timeout failover.
{
"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"
}{
"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.eventType.Sign the exact UTF-8 request body using HMAC-SHA256 and the global provider webhook secret.
Content-Type: application/json; charset=utf-8
X-Platform-Signature: LOWERCASE_HEX_HMAC_SHA256Use lowercase hexadecimal only. Do not add Bearer or sha256=. Sign the bytes you send, not a re-serialized object.
| Secret | test-secret |
|---|---|
| Exact body | {"status":"delivered"} |
| Signature | bfebae765b7f20464b4b64d37314fc073a178a293762aaf32920be724d5fde18 |
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}`);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();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()| FleetBridge operation | Automatic retry | Why |
|---|---|---|
| Create | Up to 3 total attempts | Same idempotency key |
| Status, tracking, test | Up to 3 total attempts | Safe operation |
| Update, cancel, return | No transparent retry | Outcome may be ambiguous |
FleetBridge retries after network failure, timeout, 429, or 5xx. It honors Retry-After up to 30 seconds.
Retry-After.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.
Declare only working behavior that passes generated tests.
| Capability | Meaning | Evidence |
|---|---|---|
supportsWebhook | Signed lifecycle events | Signature, retry, duplicate, routing |
supportsPolling | Status converges | Lifecycle and unknown delivery |
supportsTrackingUrl | Usable tracking URL | Tracking response |
supportsDriverLocation | Driver coordinates | Tracking and location event |
supportsEta | Delivery ETA | Tracking and ETA event |
supportsProofOfDelivery | Proof artifact | Must be false in v1.1 |
supportsExternalReference | Persists platformReference | Create and every event |
supportsIdempotencyKey | Durable idempotency | Replay, conflict, concurrency, restart |
supportsCancellationBeforePickup | Early cancellation | Controlled test |
supportsCancellationAfterPickup | Late cancellation | Controlled test |
supportsOrderUpdate | General updates | Field-by-field PATCH |
supportsAddressUpdate | Destination update | PATCH |
supportsPhoneUpdate | Phone update | PATCH |
supportsScheduledDelivery | Scheduled create | Scheduled fixture |
supportsScheduledDeliveryUpdate | Schedule changes | PATCH |
supportsReturnToOrigin | Return endpoint | Controlled return |
A provider supports at least one of webhook or polling. A stub or roadmap item is not a capability.
{
"code": "validation_failed",
"message": "Request validation failed.",
"retryable": false,
"fieldErrors": {
"currency": ["Must be three uppercase characters."],
"dropoffLat": ["Must be between -90 and 90."]
}
}| HTTP | Meaning | Action |
|---|---|---|
| 400 | Malformed request | Correct request |
| 401 | Missing or invalid token | Correct credentials |
| 403 | Valid token lacks access | Correct authorization |
| 404 | Unknown delivery | Do not retry |
| 409 | Idempotency, callback, or state conflict | Reconcile |
| 422 | Invalid or unsupported values | Correct payload |
| 429 | Rate limited | Retry using Retry-After |
| 500 | Unexpected failure | Retry safe operations |
| 502/503 | Transient unavailable dependency | Retry safe operations |
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.
FleetBridge generates safe test data, runs supported operations, and recommends capabilities from observed results.
FleetBridge sends POST /webhooks/test with Bearer authentication and {}. This tests reachability and authorization only. A 401 or 403 fails the test.
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
{}{
"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
}
}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.
Recognize staging credentials and IFB-TEST references. Never dispatch a generated test to a real courier or customer.
IMPLEMENTATION_DECLARED
-> STAGING_CONFIGURED
-> STAGING_CERTIFIED
-> PRODUCTION_CONFIGURED
-> PRODUCTION_CERTIFIED
Administrative states: SUSPENDED, RECERTIFICATION_REQUIREDdriver.assigned is implicit acceptance when it is the first valid provider event.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.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.
MUST and MUST NOT are mandatory. SHOULD is recommended unless a documented reason applies. MAY is optional.