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)

Property	Value
Method	POST
Content-Type	application/json
Auth	Authorization: Bearer <secret> provisioned by LogirAI at onboarding.
Retries	None — fire-and-forget, single attempt.
Timeout	10 seconds end-to-end. If your endpoint takes longer, the delivery is recorded as failed.
Order	Not guaranteed — events for the same resource may arrive out of order.
Onboarding	Manual 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.

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.

// 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
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

Header	Value
Authorization	Bearer <secret>
X-Logir-Delivery-Id	Unique per delivery — evt_<uuid>. Use for de-duplication.
X-Logir-Event	The event type (e.g. guide.delivered).
User-Agent	LogirAI-Webhook/1.0.
Content-Type	application/json.

Handling deliveries

Concern	Recommended approach
Idempotency	De-duplicate by X-Logir-Delivery-Id (also present as id on the payload).
Order	Compare timestamp / occurred_at and only forward-apply state. Don't trust receipt order.
Acknowledgement	Return 2xx only after the event is durably persisted. Avoid blocking on downstream side-effects — process async.
Failures on your side	Log the delivery and reconcile via the GET endpoints later. v1 won't redeliver.
Reconciliation	Periodically 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.