API Reference

Webhook Subscriptions

eHub allows you to subscribe to webhooks to receive real-time notifications about shipment tracking events and payment statuses. These webhooks ensure that you stay informed and can automate workflows based on the latest updates from your shipments and payments.

Subscription Types

Shipment Tracking

Subscribe to receive tracking events for all shipments created under a single eHub account. Each child account will need its own subscription for individual tracking updates.
Use Case: Automate tracking updates, monitor shipment progress, and notify customers of delivery status in real time.

Payment Status

Subscribe to receive updates on payment status for shipment transactions made through eHub. The webhook will notify you of accepted, rejected, and returned payments.
Use Case: Track payment statuses, handle discrepancies, and efficiently manage refunds or payment issues.

Webhook Statuses

Webhooks can return the following statuses:

active: The webhook is functioning and sending notifications as expected.
error_disabled: The webhook has been disabled due to multiple consecutive errors, such as timeouts or failed deliveries.

Note: After 5 consecutive failed responses from the receiving system the webhook will automatically be updated to have a disabled status.

Parameters in the Response

error_count: Number of errors received from the upstream source.
last_response_code: The most recent HTTP status code from the upstream source.
last_response_message: The message corresponding to the last HTTP status code.

Disabled Subscriptions

If a webhook request times out (fails to receive a successful response within 30 seconds), it will be marked as disabled after consecutive failures. You can avoid this by saving the payload locally, responding with success, and then processing the payload asynchronously.

Tracking Event payload example:

Plain text

 {
  "subscription_type": "shipment_tracking",
  "status": "active",
  "payload": [
    {
      "shipment_id": 115,
      "tracking_number": "9400109205328003425036",
      "tracking_event_id": 539,
      "parcel_id": 115,
      "code": "01",
      "secondary_code": "01",
      "description": "Delivered, In/At Mailbox",
      "event_timestamp": "2018-11-13T00:00:00.000Z",
      "city": "New Oceane",
      "state": "CA",
      "postal_code": "34668-2801",
      "country": "US"
    },
    {
      "shipment_id": 115,
      "tracking_number": "9400109205328003425036",
      "tracking_event_id": 540,
      "parcel_id": 115,
      "code": "OF",
      "secondary_code": null,
      "description": "Out for Delivery",
      "event_timestamp": "2018-11-12T19:00:24.000Z",
      "city": "Lake Jett",
      "state": "LA",
      "postal_code": "91251-7728",
      "country": "US"
    }
  ]
}

code and secondary_code vary by carrier. For USPS the codes are documented in Publication 199, Appendix G-4 (https://postalpro.usps.com/impbimplementationguide).

Payment Status payload example: