Orbit's webhooks facilitate real-time data provision, allowing your application to respond to events as they transpire, without the need for constant polling for changes. This results in a more efficient and often more effective system, reducing server strain.
Consider these webhook events as a reverse API call. Rather than your application requesting data from our API, orbit pushes the data directly to your application as the specified event takes place.
Orbit's webhooks can be set up to notify about a variety of events. These could include the creation of a new tour, the completion of a tour, or a new shipper registration. By subscribing to these events, your application can automate tasks, align data, or even interact with other systems, thereby streamlining your processes.
You can set up webhooks in orbit through MissionControl under Settings -> Webhooks.
Authorization
Webhook authorization ensures that incoming requests to your endpoints are genuinely from Orbit, protecting your application from unauthorized or malicious requests. This security layer prevents data tampering and maintains the integrity of your webhook integrations.
Orbit supports two authentication methods for webhook delivery:
Basic Authentication
Basic authentication uses a username and password combination that you configure when setting up your webhook. Orbit includes these credentials in the standard HTTP Authorization header using Base64 encoding. This method provides straightforward security and is widely supported across platforms and frameworks.
HMAC Authentication
HMAC (Hash-based Message Authentication Code) provides cryptographically secure authentication using a shared secret. This method offers superior security as the secret never travels over the network.
HMAC uses the HMAC-SHA256 algorithm with your configured secret key. The signed payload always includes the epoch timestamp in seconds and is dot-separated with the stringified JSON body (timestamp.raw_json_body). The signature is encoded in lowercase hexadecimal format.
Headers set by HMAC Authentication:
| Header | Value |
|---|---|
| X-Signature-Algorithm | hmac-sha256 |
| X-Signature-Timestamp | Unix epoch seconds |
| X-Signature | The computed HMAC signature |
To verify authenticity, recreate the signature using your secret and compare it with the received signature. Most applications implement a replay window (typically 5 minutes) to prevent replay attacks by rejecting requests with timestamps outside the acceptable range. HMAC authentication is recommended for production environments requiring enhanced security.
Types and Payloads
In the subsequent table, we provide a description of each webhook event type and the corresponding payload format.
| Event Type | Payload | ||
|---|---|---|---|
| tour-created | {tour: Tour} | ||
| tour-assigned | {tour: Tour} | ||
| tour-unassigned-carrier | {tour: Tour} | ||
| tour-started | {tour: Tour} | ||
| tour-arrived-at-stop | {tour: Tour} | ||
| tour-departed-from-stop | {tour: Tour} | ||
| tour-proof-attached | {tour: Tour} | ||
| tour-waiting-for-review | {tour: Tour} | ||
| tour-completed | {tour: Tour} | ||
| tour-cancelled | {tour: Tour} | ||
| tour-deleted | {tourId: String} | ||
| tour-edited | {tour: Tour} | ||
| shipments-created | {shipments: Shipment[]} | ||
| shipment-deleted | {shipmentId: String} | ||
| shipment-updated | {shipment: Shipment} | ||
| order-created | {order: Order} | ||
| order-updated | {order: Order} | ||
| shipper-created | {shipper: Shipper} | ||
| shipper-updated | {shipper: Shipper} | ||
| shipper-team-created | {shipperTeam: ShipperTeam} | ||
| shipper-team-updated | {shipperTeam: ShipperTeam} | ||
| shipper-user-created | {shipperUser: ShipperUser} | ||
| shipper-user-updated | {shipperUser: ShipperUser} | ||
| mailbox-created | {mailbox: MailBox} | ||
| mailbox-mail-received | {mailboxId: String} | ||
| mailbox-status-changed | {mailboxId: String, newStatus:"active" | "inactive", newStatus:"active" | "inactive"} |
| decode-job-result | {jobId: String, resultType: "success" | "failure"} | |
| transport-drafts-deleted | {transportdraftIds: String[]} | ||
| sequence-invocation-created | {sequenceInvocation: SequenceInvocation} | ||
| sequence-invocation-action-created | {sequenceInvocationAction: SequenceInvocationAction} | ||
| callout-action-created | {callouts: CalloutWithStats[], action: CalloutAction, notifyAll?: Boolean, except?: String[]} |