Skip to main content

Webhooks

Webhook endpoints let partners receive shipment and pickup updates in near real time.

Create webhook subscription​

POSThttps://api.aquiline-tracking.com/v3/webhooks/subscriptions

Creates a webhook subscription for shipment and pickup events.

Subscription modes:

  • Global scope: receive events for all shipments in your partner context.
  • Tracking scope: receive events only for a specific trackingNumber.

Key request fields:

  • webhookUrl
  • events
  • secret
  • trackingNumber (optional; when set, events are delivered only for this tracking number)

webhookUrl requirements:

  • Must be an absolute https:// URL (TLS required).
  • Must be publicly reachable (no localhost/private-only addresses).
  • Must accept POST requests with Content-Type: application/json.
  • Must return a 2xx status code to acknowledge delivery.
  • Should complete response quickly (recommended under 5 seconds).
  • Should not depend on browser sessions/cookies or interactive auth.
  • Should process duplicate deliveries idempotently.
  • If secret is configured, endpoint should verify X-Webhook-Signature before processing payload.

Required headers for subscription management:

  • X-API-Key
  • X-Partner-Id

X-API-Key must belong to the same partner context as X-Partner-Id. Requests with a mismatched pair are rejected with 401 Unauthorized.

Example request (track-specific):

curl -X POST "https://api.aquiline-tracking.com/v3/webhooks/subscriptions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "X-Partner-Id: partner_123" \
  -d '{
    "webhookUrl": "https://partner.example.com/webhooks/aquiline",
    "events": ["shipment.in_transit", "shipment.delivered", "shipment.exception"],
    "trackingNumber": "AQUAA0849240326YQ",
    "secret": "whsec_very_secret_value"
  }'

Example success response:

{
  "success": true,
  "id": "whs_01J2V6FQ2M9Q"
}

List webhook subscriptions​

GEThttps://api.aquiline-tracking.com/v3/webhooks/subscriptions

Returns the current webhook registrations for the authenticated partner context.

Example request:

curl -X GET "https://api.aquiline-tracking.com/v3/webhooks/subscriptions" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "X-Partner-Id: partner_123"

Example success response:

{
  "success": true,
  "subscriptions": [
    {
      "id": "whs_01J2V6FQ2M9Q",
      "partnerId": "partner_123",
      "webhookUrl": "https://partner.example.com/webhooks/aquiline",
      "events": ["shipment.in_transit", "shipment.delivered", "shipment.exception"],
      "trackingNumber": "AQUAA0849240326YQ",
      "secret": null,
      "isActive": true,
      "createdAt": { "_seconds": 1774354295, "_nanoseconds": 376000000 },
      "updatedAt": { "_seconds": 1774354295, "_nanoseconds": 376000000 }
    }
  ]
}

Tracking-scoped subscriptions​

To receive updates only for selected shipments, create a subscription with:

  • trackingNumber
  • an event list relevant to your workflow (shipment.in_transit, shipment.delivered, shipment.exception, etc.)

This is the recommended pattern for customer-facing alerts and operational workflows.

Webhook delivery format​

When an event is triggered, your endpoint receives:

{
  "type": "shipment.delivered",
  "occurredAt": "2026-03-23T10:02:15Z",
  "data": {
    "trackingNumber": "AQUAA0849240326YQ",
    "status": "Delivered",
    "statusCode": "delivered",
    "changeType": "event_append",
    "newEvents": [
      {
        "date": "2026-03-23",
        "time": "10:01",
        "message": "Delivered",
        "location": "Dubai",
        "status": "delivered"
      }
    ]
  }
}

Event mapping behavior:

  • delivered -> shipment.delivered
  • out_for_delivery -> shipment.out_for_delivery
  • exception -> shipment.exception
  • in_transit -> shipment.in_transit
  • any other status code -> shipment.updated

Status-change policy:

  • If shipment status changes but no new timeline event is appended, a webhook is still sent.
  • In that case, payload keeps newEvents: [] and sets data.changeType: "status_change".
  • For timeline additions, data.changeType is event_append.

If secret is configured, each delivery includes:

  • X-Webhook-Signature: sha256=<hex(hmac_sha256(secret, rawBody))>

Use this to verify authenticity before processing.

Delivery behavior:

  • Delivery timeout per attempt: 8 seconds.
  • Retries on timeout/non-2xx responses with backoff: 1s, 5s, 20s.
  • Subscription health fields are tracked internally (lastDeliveryStatus, lastAttemptAt, failureCount).
  • Delivery logs are retained for 90 days.

Authentication model​

X-API-Key must be a server-issued partner key bound to your partner context.
Do not use an end-user identifier (or dashboard user id) directly as X-API-Key.

Recommended access model:

  1. Partner onboarding creates a stable partnerId.
  2. Aquiline issues and rotates API keys for that partner.
  3. Partner calls webhook subscription APIs with:
    • X-API-Key (secret credential)
    • X-Partner-Id (routing/ownership identifier)

This keeps auth secure, rotatable, and operationally manageable.

  • shipment.in_transit
  • shipment.out_for_delivery
  • shipment.delivered
  • shipment.exception
  • pickup.updated

Notes for list response fields:

  • createdAt and updatedAt are returned as Firestore timestamp objects (_seconds, _nanoseconds).

Delete webhook subscription​

DELETEhttps://api.aquiline-tracking.com/v3/webhooks/subscriptions/{id}

Deactivates a webhook subscription. Deactivated subscriptions are excluded from delivery and list results.

Example request:

curl -X DELETE "https://api.aquiline-tracking.com/v3/webhooks/subscriptions/whs_01J2V6FQ2M9Q" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "X-Partner-Id: partner_123"

Example success response:

{
  "success": true,
  "id": "whs_01J2V6FQ2M9Q",
  "isActive": false,
  "expiresAt": "2026-06-22T13:30:00.000Z"
}