Receive delivery updates with RouteIQ Dispatch Software webhooks
Send delivery status changes to your order system or agent without repeatedly polling every job. Subscribe an HTTPS endpoint to RouteIQ Dispatch Software events and verify each request before processing it.
Choose the events your system needs
Use webhooks when another system should respond to work happening in RouteIQ. For example, an order system can update its delivery status when a job changes state, while a reporting system may need stop-level progress.
Subscribe to the smallest useful set of events. A job-state change and a stop-state change describe different records; subscribe to both only if your receiver uses both. Webhooks carry updates to your system. Use the API when your system needs to create or retrieve work.
Have an administrator configure the subscription in the correct site, and have the integration developer prepare a public HTTPS endpoint that verifies signatures and handles repeated delivery. An API key authorizes API calls; a separate webhook signing secret lets your receiver verify webhook requests.
Set up the subscription in the Dashboard
- Open Settings → Webhooks and select Add Webhook.
- Enter the receiver's public HTTPS address in URL.
- Choose the Events your receiver needs, such as
job:state_changeandstop:state_change. - Enter a securely generated signing value in Secret Key and store the same value in the receiver's secret configuration. The field is optional in the form, but use a secret when your receiver verifies signatures as described below.
- Leave Is Active selected when the endpoint is ready to receive requests, or clear it while you finish setup. Select Create.
- Confirm the saved URL, event list, and Active state in the table. A Secret Key badge indicates a secret is configured; it does not reveal the value.
Change a test job through its normal workflow, then confirm the receiver records the event and your downstream system handles it correctly. Saving the subscription alone does not test endpoint delivery.
RouteIQ does not return the saved secret. When editing in the Dashboard, the field is blank: leave it blank to keep the existing secret, or enter a new value to replace it. A blank field on a new subscription creates it without a signing secret.
Create a subscription through the API
Deploy an HTTPS endpoint reachable from RouteIQ Dispatch Software. Localhost and private network addresses are not suitable delivery targets. Use an API key with webhook-management permission and generate a separate signing secret.
The example below requires curl, jq, and OpenSSL. Replace the site, API key, and endpoint. Store ROUTEIQ_WEBHOOK_SECRET securely on both the receiver and the subscription; it is different from your API key.
export ROUTEIQ_BASE_URL="https://YOUR-SITE.routeiq.app/api"
export ROUTEIQ_API_KEY="YOUR-API-KEY"
export WEBHOOK_URL="https://YOUR-DOMAIN.example/routeiq"
export ROUTEIQ_WEBHOOK_SECRET="$(openssl rand -hex 32)"
jq -n --arg url "$WEBHOOK_URL" --arg secret "$ROUTEIQ_WEBHOOK_SECRET" '{
url: $url,
events: ["job:create", "job:state_change", "stop:state_change"],
secret_key: $secret,
is_active: true
}' | curl --fail-with-body --silent --show-error \
--request POST "$ROUTEIQ_BASE_URL/webhook" \
-H "x-api-key: $ROUTEIQ_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-Save the returned subscription ID. Event names are lowercase entity:action strings. The payload contains event, a UTC RFC3339 timestamp, and data for the entity. A stop event describes a stop; use its job relationship when you need the parent job.
The API does not return the stored signing secret. When updating a subscription through the API, omitting secret_key keeps it, supplying a new value replaces it, and an empty string removes it. The Dashboard omits a blank secret field, so leaving it blank there preserves the existing secret.
Verify the signature
X-Webhook-Signature is the lowercase hexadecimal HMAC-SHA256 of the exact request-body bytes, using your signing secret. Verify it with a constant-time comparison before parsing JSON. Reformatting JSON before verification changes the signature.
Download webhook-receiver.mjs. It uses Node.js 22 or later, rejects missing or invalid signatures, limits request bodies to 1 MiB, and returns a success status only after its handler finishes.
# Use the same secret you configured for the subscription. node webhook-receiver.mjs
The executable example listens on 127.0.0.1:8787 and logs the event name for local testing. Before deploying, provide its exported createReceiver(secret, accept) function with a handler that commits to a durable queue or database. Put the receiver behind your HTTPS endpoint and size its body limit for your events.
Test a signed request locally
In a second terminal with the same ROUTEIQ_WEBHOOK_SECRET, send this synthetic event. The receiver should log the event name and the client should print 204. This tests your receiver, not delivery from RouteIQ Dispatch Software.
node --input-type=module <<'JS'
import { createHmac } from 'node:crypto';
const secret = process.env.ROUTEIQ_WEBHOOK_SECRET;
if (!secret) throw new Error('Set ROUTEIQ_WEBHOOK_SECRET');
const body = JSON.stringify({
event: 'job:state_change',
timestamp: new Date().toISOString(),
data: { id: 'local-test-job' }
});
const signature = createHmac('sha256', secret).update(body).digest('hex');
const response = await fetch('http://127.0.0.1:8787/routeiq', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Webhook-Signature': signature
},
body
});
console.log(response.status);
JSRepeat with an incorrect secret and expect 401. For an end-to-end test, deploy the receiver, create a subscription on your test site, change a test job’s state through its normal workflow, and confirm your application processes the delivered event.
Handle retries and recovery
Return a 2xx response after processing succeeds or durable storage commits. Timeouts, network errors, and non-success responses can trigger retries with backoff. If your queue is unavailable, return a failure rather than acknowledge an event you cannot retain.
Make downstream actions idempotent. The documented envelope does not include a unique delivery ID. A hash of the exact body can identify an identical retried payload, but it is not a general business-event identifier. Use durable business keys and current entity state to prevent duplicate notifications, charges, or assignments.
Do not assume event arrival order matches workflow order. When an update is missing or arrives late, read GET /job/{id} and reconcile your state.
A subscription can be deactivated when retries are exhausted, or immediately for 404, 410, or an unresolvable target. Monitor its status with GET /webhook?id=WEBHOOK-ID, repair the endpoint, and reactivate it with PUT /webhook?id=WEBHOOK-ID using the documented subscription fields and is_active: true. Do not assume reactivation replays missed events.
See the API reference for webhook operations and the dispatch guide for creating test work.
Edit, pause, or remove the subscription
In Settings → Webhooks, use the row's Edit action to change its URL, events, secret, or active state, then select Update. Check the saved row and repeat the end-to-end test after a change.
- Pause delivery: turn off the row's Active control, or clear Is Active in the edit form. The saved secret is preserved when toggling activity.
- Replace the signing secret: coordinate the change with the receiver, enter the replacement in Secret Key, and update the receiver to match. An outdated receiver secret causes signature verification to fail.
- Remove the subscription: open its Actions menu, choose Delete, and confirm once the downstream workflow no longer needs it.
No event arrives
Check the site, selected event, active state, public endpoint URL, and receiver logs. Confirm that the test action emitted the event you subscribed to. A locally signed test validates the receiver but does not prove RouteIQ reached it.
The receiver rejects a signature
Confirm both sides use the same signing secret and that verification uses the exact incoming bytes. If the secret was replaced, update the receiver; the Dashboard cannot retrieve the previous value.
The subscription became inactive
Repair the receiving endpoint and review retry failures before reactivating it. Reconcile current job state through the API for any missed work; turning the subscription back on does not guarantee replay.