Skip to content

Webhooks — Overview ​

LogirAI POSTs your endpoint every time one of your shipments changes state — pre-alert ingested, customs status changes, out-for-delivery, delivered, exceptions. The full event catalog lives in Client Webhooks (ES). This page covers the delivery contract.

Delivery characteristics (v1) ​

PropertyValue
MethodPOST
Content-Typeapplication/json
AuthAuthorization: Bearer <secret> provisioned by LogirAI at onboarding.
RetriesNone — fire-and-forget, single attempt.
Timeout10 seconds end-to-end. If your endpoint takes longer, the delivery is recorded as failed.
OrderNot guaranteed — events for the same resource may arrive out of order.
OnboardingManual via LogirAI ops. No self-service in v1.

v1 has no retries

If your endpoint is unavailable when the event fires, the event is lost. Reconcile via GET /api/public/pre-alerts/v1/mawbs (or /v1/guides/:tracking_code for a single shipment) at least once per shift, or accept the loss.

Authentication ​

Each delivery includes a Bearer token in the Authorization header. The token is the secret you provisioned with LogirAI at onboarding.

http
POST https://your-app.com/webhooks/logirai HTTP/1.1
Authorization: Bearer YOUR_WEBHOOK_SECRET
Content-Type: application/json
User-Agent: LogirAI-Webhook/1.0
X-Logir-Delivery-Id: evt_e37af6c2-9275-4dd1-9e94-d2726245d38c
X-Logir-Event: guide.delivered

Verify the Bearer with a constant-time comparison against your stored secret. Reject mismatches with 401.

js
// Node.js
import crypto from 'node:crypto'
function verifyBearer(authHeader, expectedSecret) {
  const m = /^Bearer\s+(.+)$/.exec(authHeader || '')
  if (!m) return false
  return crypto.timingSafeEqual(
    Buffer.from(m[1]),
    Buffer.from(expectedSecret)
  )
}
python
# Python
import hmac
def verify_bearer(auth_header: str, expected_secret: str) -> bool:
    if not auth_header or not auth_header.startswith("Bearer "):
        return False
    return hmac.compare_digest(auth_header[7:], expected_secret)

Standard headers on every delivery ​

HeaderValue
AuthorizationBearer <secret>
X-Logir-Delivery-IdUnique per delivery — evt_<uuid>. Use for de-duplication.
X-Logir-EventThe event type (e.g. guide.delivered).
User-AgentLogirAI-Webhook/1.0.
Content-Typeapplication/json.

Handling deliveries ​

ConcernRecommended approach
IdempotencyDe-duplicate by X-Logir-Delivery-Id (also present as id on the payload).
OrderCompare timestamp / occurred_at and only forward-apply state. Don't trust receipt order.
AcknowledgementReturn 2xx only after the event is durably persisted. Avoid blocking on downstream side-effects — process async.
Failures on your sideLog the delivery and reconcile via the GET endpoints later. v1 won't redeliver.
ReconciliationPeriodically GET the canonical resource — webhooks are an optimization, not the system of record.

Onboarding ​

Webhook subscriptions are not self-serve in v1. To activate, change, or rotate a subscription:

  1. Send your HTTPS destination URL and a technical contact to your LogirAI integration partner. Plain HTTP is rejected.
  2. LogirAI returns a Bearer secret for the Authorization header.
  3. Store it in your secret manager. Rotation is immediate, no grace period.

Roadmap ​

These items are planned for v2. Track progress on the Changelog.

  • HMAC-SHA256 signatures (X-LogirAI-Signature) in addition to the Bearer header.
  • Per-event subscription with filters.
  • Retries with exponential backoff and a dead-letter queue.
  • Replay endpoint for recovering missed events.
  • Self-service subscription management.

LogirAI — Cross-Border Logistics API for Retailers and Marketplaces