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, or programmatically with your API key through the Webhooks endpoints: POST /webhooks registers one (target URL, events, optional per-event filters, authentication), GET /webhooks and GET /webhooks/{webhookId} read them back with every secret masked, and DELETE /webhooks/{webhookId} removes one. The request shape and validation are the same on both surfaces; there is no update endpoint — delete and re-create to change a webhook.
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 three authentication methods for webhook delivery. Whichever you choose, the secret is stored write-only: once saved it is never shown or returned again, and editing a webhook without retyping it keeps the stored value. To change a secret, enter the new one.
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.
Bearer Token Authentication
Bearer token authentication sends a token you configure in the standard HTTP Authorization header:
| Header | Value |
|---|---|
| Authorization | Bearer <your-token> |
The token travels with every delivery, so use it only over HTTPS. It suits endpoints that already accept an API token, and it is the simplest option to verify: compare the received token against the one you configured. For a secret that never crosses the network at all, use HMAC instead.
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.
Delivery & Timeouts
Each event is delivered as an HTTP POST with a JSON body and an X-Delivery-Id header. The delivery ID identifies one delivery, that is one event for one webhook, and stays the same across every attempt of that delivery. Use it to deduplicate on your side: a delivery can reach you more than once, for example when your endpoint processed a request but answered too late.
Orbit waits up to 20 seconds for your endpoint to respond. Acknowledge receipt quickly and handle longer processing asynchronously.
Retries
A delivery counts as successful when your endpoint answers with a 2xx status. Orbit retries a delivery when your endpoint answers with a 5xx status or with 429, when it does not answer within 20 seconds, or when it cannot be reached. Any other status, for example 400, 401 or 404, ends the delivery at once, because repeating the same request would not change the answer.
A delivery gets up to 6 attempts over about 24 hours. After the first attempt the waiting times are 1 minute, 10 minutes, 1 hour, 6 hours and 16 hours. Every attempt sends the same body and the same X-Delivery-Id. Authentication is computed again for each attempt, so with HMAC the X-Signature-Timestamp and the X-Signature differ between attempts. A retry uses the webhook as it is configured at that moment: a changed target URL or changed credentials apply to the next attempt.
Retries do not preserve order. While one delivery waits for its next attempt, newer events for the same entity are delivered right away, so a retried delivery can arrive after a newer one. The payload carries the state of the entity at the time of the event.
Automatic disabling
When every delivery to a webhook has failed for three days, Orbit disables the webhook. The three days start when a delivery has failed for good, that is after its last attempt, and a single successful delivery resets them. A disabled webhook receives no further events, and deliveries that were still waiting for a retry are discarded.
When a webhook is disabled, Orbit sends an email: to the user who created the webhook, or, if it was created with an API key or that user is no longer active, to the alert recipients configured for your account, and otherwise to your administrators.
The webhook object shows the state in three fields: failingSince (when the current run of failures began; absent while the webhook is healthy), disabledAt and disabledReason (both absent while the webhook is enabled). You can read them through GET /webhooks and GET /webhooks/{webhookId}.
A disabled webhook is re-enabled in MissionControl under Settings -> Webhooks. There is no API endpoint for it; through the API you can delete the webhook and create it again.
Catching up on missed events
Orbit does not store delivery payloads and cannot send a delivery again once its attempts are used up or it was discarded. After an outage, bring your system up to date by reading the changes through the list endpoints of the API, using their updatedSince filter where it is available, instead of waiting for the missed events.
Filtering Deliveries
Each event subscription can optionally carry a filter — a set of conditions evaluated against the event's payload before delivery. When a filter is set, Orbit only sends the webhook if the payload matches; non-matching events are skipped silently without an HTTP request. This lets you subscribe to a busy event type while receiving only the deliveries you care about, e.g. tour-completed only for tours of a specific region, or shipment-updated only when the shipment has reached a specific status.
Filters are configured per event in MissionControl under Settings -> Webhooks: enable an event, then choose Add Filter on its row. The available fields are derived from that event's payload (the same shape documented in the table below, using dotted paths such as tour.status), so a filter can only reference data the delivery actually contains.
Your own custom properties — the ones created in MissionControl under Settings -> Properties — are filterable too. A property appears as the field <entity>.properties.<propertyId> on events that deliver the whole entity it is defined on, so a property on Tour can be filtered on tour-completed while a property on Order can be filtered on order-updated (id-only events such as tour-deleted offer no property fields). Text, number, checkbox and select properties are filterable today; multiselect, tags and document properties are listed in the field picker but cannot be selected yet. Select conditions compare against the option's id, and the picker inserts it for you when you choose the option by name. On order-created, fields of the optional tour payload entity offer no "is set" / "is not set" conditions — an order without a tour has no tour entity to check them against.
Two events deliver a list rather than a single entity: shipments-created carries an array of shipments and transport-drafts-created an array of transport drafts, so neither offers per-shipment or per-draft filter fields yet — filter shipment-updated instead when you need shipment-level conditions.
A few semantics worth knowing:
- Conditions within a group combine with AND by default (every condition must match); a group can be switched to OR (any condition may match), and groups can be nested.
- Text conditions (
contains,begins with,ends with,equals) match literally and case-sensitively. Each has a negated form (does not contain,does not begin with,does not end with,does not equal). - A negated text condition also matches when the field carries no value. A custom property that was never set, or an optional payload field the event omits, is not equal to anything and contains nothing, so
does not equal Xdelivers those events as well. - Date conditions compare against calendar days anchored at Europe/Berlin.
- A skipped delivery is not a failure: it does not consume retries and never triggers failure alerting. Your endpoint simply doesn't hear about the event.
- A subscription without a filter behaves exactly as before — it fires for every occurrence of the event.
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} — fired by the last advance, by a carrier-reported delivery, or by manual-complete |
| tour-completed | {tour: Tour} |
| tour-cancelled | {tour: Tour} |
| tour-deleted | {tourId: String} |
| tour-edited | {tour: Tour} |
| tour-rebuilt | {tour: Tour, action: TourAction} |
| tour-action-created | {tour: Tour, action: TourAction, oldStatus?: String, newStatus?: String, deviceTime: Number, receivedAt: Number, conflict: Boolean} |
| shipments-created | {shipments: Shipment[]} |
| shipment-deleted | {shipmentId: String} |
| shipment-updated | {shipment: Shipment} |
| order-created | {order: Order, tour?: Tour, tours?: Tour[], documentLinks?: DocumentLink[]} |
| order-action-created | {order: Order, action: OrderAction} |
| order-updated | {order: Order} |
When an order cancellation removes the last shipment from a tour with an assigned carrier, Orbit emits tour-cancelled for that tour instead of tour-deleted.
| operator-user-invite-created | {operatorUserInvite: OperatorUserInvite} |
| operator-user-created | {operatorUser: OperatorUser} |
| shipper-created | {shipper: Shipper} |
| shipper-updated | {shipper: Shipper, action: ShipperAction} |
| shipper-team-created | {shipperTeam: ShipperTeam} |
| shipper-team-updated | {shipperTeam: ShipperTeam, action: ShipperTeamAction} |
| shipper-user-created | {shipperUser: ShipperUser} |
| shipper-user-updated | {shipperUser: ShipperUser, action: ShipperUserAction} |
| shipper-address-created | {shipperAddress: ShipperAddress} |
| mailbox-created | {mailbox: Mailbox} |
| mailbox-mail-received | {mailboxId: String} |
| mailbox-status-changed | {mailboxId: String, newStatus: "active" | "inactive", oldStatus: "active" | "inactive"} |
| decode-job-result | {transportDraft: TransportDraft} |
| callout-action-created | {callouts: CalloutWithStats[], action: CalloutAction} |
| sequence-created | {sequence: Sequence} |
| sequence-updated | {sequence: Sequence} |
| sequence-invocation-created | {sequenceInvocation: SequenceInvocation} |
| sequence-invocation-action-created | {sequenceInvocationAction: SequenceInvocationAction} |
| dispatch-run-created | {dispatchRunId: String, tourId: String} |
| dispatch-run-action-created | {actionId: String, dispatchRunId: String, tourId: String, type: "created" | "fired" | "sequence-started" | "sequence-failed" | "assigned" | "no-result" | "cancelled"} |
| transport-drafts-created | {transportDrafts: TransportDraft[]} |
| transport-drafts-deleted | {transportDraftIds: String[]} |
| transport-draft-action-created | {transportDraft: TransportDraft, action: TransportDraftAction} |
| vehicle-created | {vehicle: Vehicle} |
| vehicle-action-created | {vehicle: Vehicle, action: VehicleAction} |
| vehicle-deleted | {vehicle: Vehicle} |
| carrier-created | {carrier: Carrier} |
| carrier-action-created | {carrier: Carrier, action: CarrierAction} |
| carrier-team-created | {carrierTeam: CarrierTeam} |
| carrier-team-action-created | {carrierTeam: CarrierTeam, action: CarrierTeamAction} |
| carrier-user-created | {carrierUser: CarrierUser} |
| carrier-user-action-created | {carrierUser: CarrierUser, action: CarrierUserAction} |
| document-link-action-created | {documentLink: DocumentLink, action: DocumentLinkAction} |
| leg-created | {leg: Leg} |
| leg-action-created | {leg: Leg, action: LegAction} |
| leg-deleted | {leg: Leg} |
| transport-draft-recurring-activated | {transportDraft: TransportDraft} |
| transport-draft-recurring-paused | {transportDraft: TransportDraft} |
| transport-draft-recurring-resumed | {transportDraft: TransportDraft} |
| transport-draft-recurring-ended | {transportDraft: TransportDraft} |
| comment-created | {comment: Comment} |
| comment-edited | {comment: Comment} |
| comment-deleted | {comment: Comment} |
| comment-reaction-added | {comment: Comment, reaction: CommentReaction} |
| comment-reaction-removed | {comment: Comment, reaction: CommentReaction} |
| task-created | {task: Task, referencedEntity: {orn: String, type: String, id: String}, deviceTime: Number, receivedAt: Number} |
| task-completed | {task: Task, referencedEntity: {orn: String, type: String, id: String}, deviceTime: Number, receivedAt: Number} |
| task-skipped | {task: Task, referencedEntity: {orn: String, type: String, id: String}, deviceTime: Number, receivedAt: Number} |
| task-cancelled | {task: Task, referencedEntity: {orn: String, type: String, id: String}, deviceTime: Number, receivedAt: Number} |
| task-action-created | {task: Task, referencedEntity: {orn: String, type: String, id: String}, action: TaskAction, deviceTime: Number, receivedAt: Number} |
| emissions-updated | {piece: {id: String, status: "estimate" | "final" | "withdrawn", version: Number, correction: Object | null}, emissions: Emissions object} |
Notes on order-created
order-created- An order can create several tours at once: one for every shipment group of the request that asks for a tour, or one per shipment when it is booked that way.
tourslists all of them in creation order, each in the same shape astour. touris always the first entry oftours, so an integration that reads onlytourkeeps working for orders with a single tour. Readtoursto learn about every tour.- Both fields are absent when the order created no tour.
- Delivery filters address
touronly.toursis a list, and filter fields cannot address list entries.
Notes on order-action-created
order-action-created- Fires for every order action and carries the bounded current
orderplus theactionthat was recorded.order-updatedremains the order-only compatibility event. - Filter
action.payload.typeto subscribe to specific actions, such assubmit-to-accounting. - Accounting submission snapshots on both
orderandaction.payloadare bounded to status, provider, external id/number, submitted time, needs-update state and the last error message. Provider URLs, request ids, hashes, steps, logs and internal status timestamps are not sent.
Notes on tour-action-created
tour-action-created- Fires for every action on a tour — status advances, reversals (
reverse), resets (reset), manual completions (manual-complete), assignments, edits, rebuilds, proof attachments, and more — making it the one subscription that observes the tour's complete activity stream, including backwards status transitions that no lifecycle event covers. action.payload.typeidentifies the action. Combine this event with a delivery filter (see "Filtering Deliveries" above) onaction.payload.typeto receive only the actions you care about, e.g. onlyreverseandreset.deviceTimeis when the action happened, in epoch seconds: the time the driver's device or the calling system recorded it, corrected for a wrong device clock and never later thanreceivedAt, the time the platform received it. Stop and delivery times on thetourfollowdeviceTime. AreceivedAtwell afterdeviceTimemeans the action was reported late, for example after the device was offline. The individualtour-*lifecycle events keep their payload unchanged; theirtoursnapshot carries the same stop times.oldStatus/newStatuscarry the tour's status before and after the action. They are only present when the originating commit relayed its status snapshot onto this action (the first action of a commit); when present and equal, the action did not change the tour's top-level status (the change may be intour.substatus).- For
advanceactions,action.payload.capturedLocationis the optional device location and accuracy recorded for that advance. Load status updates carried by a departure use the same location. conflictistruewhen the action is a clarification case: a step reported from the driver app (anadvanceor a single execution step) does not fit the tour, for example a stop that was removed meanwhile, two devices reporting different values, a departure with loads left without a status, or a report from before the tour was reassigned. The step is recorded and the driver is never held up;action.outcomesays what happened (kind,reasons,alternatives). For every clarification case the platform opens a task withorigin: "conflict"for the operators, whosereferencedEntityis the action (type: "action",id: the action'sclientActionId, ORNorn:<tenant-id>:tour/<tourId>/action/<clientActionId>); itstask-createdandtask-completedwebhooks follow the usual task events. Cases of one tour with the same cause share one task while it is open: steps reported after the tour was cancelled, unassigned or completed, from an earlier assignment, for a stop or load no longer on the tour, or with several possible successor loads. The first such case opens the task and is itsreferencedEntity; every further case joins it without a lifecycle event of its own (it arrives astask-action-createdwithaction.payload.typeadd-case), and the task's name counts the cases. Once that task is completed or cancelled, the next case opens a new one. A tour with an open conflict task cannot be reviewed: the review is refused with409and the error codeOPEN_CONFLICT_TASKSuntil the task is completed or cancelled. Automations keep running on a clarification case; filter onconflictto single it out.- Prefer this event over the individual
tour-*lifecycle events for new integrations that mirror tour state — the lifecycle events remain supported, but new action types are surfaced here only. - Carrier-integration internals are redacted from the delivered
action: raw carrier-provider payloads (e.g. on system-generated carrier status updates) are stripped, and any internal carrier-booking record is reduced to its bounded identifiers (provider,carrierId,carrierBookingId,trackingRef) with integration internals removed — a policy analogous to the bounded carrier-booking view exposed on thetourobject itself. System-stamped internal routing fields (such as the pre-assign carrier reference onassignactions) are likewise omitted, matching the action shape of the REST API.
Notes on callout-action-created
callout-action-createdcalloutscontains only the callouts the action actually modified (e.g. a decline carries just the declining carrier's callout; creating callouts carries the newly activated ones) — it is not the cluster's full callout list.- Each callout is enriched with its cluster's bidding stats (
currentBid,bidCount,isWinning,suggestedBid). For secret auctions onlysuggestedBidis included — bid state is never revealed. action.payloadmirrors the request that drove the transition; internal dispatch context (such as system cancel reasons) is stripped.tourcarries the id and custom properties of the tour the callouts are for, so you can filter this event ontour.properties.<propertyId>— for example to receive only the callout activity for one shipper. Filtering on the callouts themselves is not possible:calloutsis a list, and filter fields cannot address list entries.touris deliberately onlyidandproperties, not the whole tour: everything else a tour carries may belong to other customers loaded on the same trip. Read the tour fromGET /tours/{id}when you need more than the properties.touris absent when the action was not raised against a tour, which happens on system cancellations. A condition on a tour field does not match such a delivery, so a filter narrows rather than leaks.action.createdAtandaction.createdAtMillisecondsare both epoch milliseconds — an explicit exception to the seconds rule in Units & formatting. The two fields carry the same value, and it matches the timestamp stored on the action record, so an event value can be compared directly against one read back from the API.- Compatibility note: before this change
action.createdAtwas delivered in epoch seconds while the stored record already held milliseconds, so the two disagreed by a factor of 1000. Deliveries sent before the change carry the old seconds value. If you persisted or comparedaction.createdAtfrom earlier deliveries, treat any value below1000000000000as seconds and multiply by 1000.action.createdAtMillisecondswas always milliseconds and is unaffected.
Notes on sequence-updated
sequence-updated- Fires after every change to a Sequence: an edit (
PATCH /sequences/{sequenceId}), an activation or deactivation, a rank action, a conversion to bricks, and a document link that fills one of its properties or whose deletion clears one.sequenceis the Sequence as stored after the change, with its newversion. The run statisticslastUsedAtandinvocationCountare not part of a change and carry no version: they hold the values the change read, so a run that started while the change was written can be missing from them.GET /sequences/{sequenceId}returns the current values. - A rank action renumbers the whole dispatch chain, so it fires once for every Sequence whose rank changed. The moved Sequence is among them only when its own rank changed.
- A request that changes nothing, such as activating a Sequence that is already active, fires nothing.
- Like
sequence-created, it carries the Sequence as stored, without thesummarythatGET /sequences/{sequenceId}answers. The summary names carriers, customers and other records as the caller of a read may see them, so it is derived for each read and never sent with a webhook.
Notes on leg events
- There are no per-status leg events: every lifecycle transition — pickup and dropoff progress, delivery, failure, cancellation, tour assignment — is delivered as
leg-action-created. The transition verb is identified byaction.payload.type, and the payload always carries the full leg as it looks after the transition. - Two leg loads can end without arriving, and they mean opposite things.
Returnedmeans this shipment's obligation for the load moved to a return shipment, so the goods are intact and travel on under that shipment.Perishedmeans the goods were written off: they no longer exist as deliverable cargo, and the leg load then carries the write-off reason (LostorDamaged), an optional note, and who wrote it off. The reason says why the goods stopped being deliverable, never what was done with them afterwards: damaged goods stay in the operator's location stock as dead stock until their disposal is recorded, and the leg load then also carriesdisposedAtanddisposedBy. ALostload never carries them. A returned load leaves the shipment un-failed because the obligation lives on elsewhere; a perished load fails it. If you classify deliveries, treatPerishedas a terminal loss and do not wait for a follow-up shipment: none is created. - Unlike
tour-deletedandshipment-deleted, which deliver only the deleted entity's id,leg-deletedcarries the full removed leg — a deleted leg can no longer be fetched from the API, so its final state is included in the delivery.
Emissions summary on entity events
tour-created,tour-action-created,shipments-created(each shipment),shipment-updated,leg-created,leg-action-createdandleg-deletedcarry anemissionsfield on their tour, shipment or leg: the same emissions summary as the entity'sGETread, with the status, the highest version, the well-to-wheel kg CO2e, the intensity in g CO2e per tonne-kilometre, whether every piece has a figure, and flags.emissionsisnullwhile no emission record exists for the entity yet. Subscribe toemissions-updatedto hear when a figure is added or changes.- The individual
tour-*lifecycle events andtour-deleteddo not carryemissions; their payloads stay unchanged.
Notes on task events
- The four
task-*lifecycle events cover the complete task lifecycle:task-createdwhen a task comes to exist, and exactly one oftask-completed,task-skipped, ortask-cancelledwhen it closes. Reassignments and the other actions below produce none of them. - The
taskobject is the task as it looks after the transition. Ontask-completedit carries the complete validated form output (task.outcome.formOutput, keyed by form element id) along with the task's kind, assignee, origin, and timestamps. A task created from a template carries the template's id intask.templateIdand, when the template has one, its stable routing label intask.templateKey; branch ontemplateKeyto route completions without dereferencing the template. - Rendered receipts arrive separately. When a task was created from a template that names a
documentTemplateId, a PDF is rendered from that document template after the task completes and linked to the task (and to its referenced entity). Thetask-completedpayload does not change and does not wait for the render; subscribe todocument-link-action-createdand filter ondocumentLink.targetEntityType === "task"to pick the receipt up, or list the task's documents. task-action-createddelivers every task action, including the ones no lifecycle event covers:reassign,snoozeandunsnooze,set-notifications,add-case(a further clarification case joining an open conflict task),delete(the platform removes an open task, for example when its stop leaves the tour or the tour is cancelled) andrestore(a removed task comes back, for example after a tour reset). An integration that mirrors open tasks subscribes to this event, so a removed task does not stay open on its side. Thedocument-attachedanddocument-detachedrows of a task's history are not delivered: they record a file upload to a task's form before it is completed, and the file reaches you with the completion's form output.actionis the action asGET /tasks/{taskId}/actionsreturns it:action.payloadis the action itself (action.payload.typeidentifies it), withaction.source,action.createdAt(epoch milliseconds) and, on a completion reported by a carrier user,action.outcome. Combine this event with a delivery filter onaction.payload.type(see "Filtering Deliveries" above) to receive only the actions you care about, e.g. onlydeleteandrestorewith an OR group of two "equals" conditions. Credentials of a form field's validation endpoint are masked inaction.payload, as in every read.taskis the task after the action. A completion a carrier user reported for a task that had been cancelled, skipped or removed meanwhile arrives withaction.outcome.kindset tologged: it is recorded, andtaskstays as it was. It is not delivered astask-completed.deviceTimeandreceivedAtare read as ontour-action-created. A subscription to bothtask-action-createdand a lifecycle event receives an action that maps to a lifecycle event twice, once per event. The four lifecycle events keep their payload unchanged.referencedEntityis a reference, not the object. Task payloads carry\{orn, type, id}parsed from the task's ORN and never embed the referenced Tour, Shipment, or other entity. Fetch the current state of the referenced entity through the API when you need it — an embedded copy would already be stale by the time your endpoint processes the delivery.
Notes on decode-job-result
decode-job-result- The payload is the transport draft the extraction ran on. What the extraction produced lives in
transportDraft.payload.data. The transport Orbit built from it, after matching against your address book, shippers and load types, istransportDraft.transport. payload.data.resultis the extraction as read from the email or document:shipmentOrderwithshipper,pickup,dropoff,loads,bookingExtras,displayName,comment,netGoodsValueandinquiryType. A value the extraction did not find is absent, nevernull.payload.data.details.textContentis a JSON string with the fieldsfrom,subject,mailReceivedAtandcontent. Parse it before use.mailReceivedAtis the email's received time, formatted as a date-time in Europe/Berlin (for example8.10.2025, 12:00). When the email carried no received time, or the document was uploaded directly, it is the time the extraction started.- The whole
textContentstring stays at or under 140,000 characters. When it would be longer,content(the email body) is truncated first. - The other fields of
payload.data.detailsare internal and may change without notice. Do not build on them.
