Webhooks & Real-time Updates
How it Works
Webhook Security
X-Signature header.How Verification Works
Verification Steps
1.
X-Signature value.2.
3.
4.
N.B. If hashsums are unequal ignore the request and return 401 UnauthorizedHTTP status to protect your system from non-certified data.
How to Set Up
Basic Information
Click “Test” to send the test event "event": "webhook.ping".
{
"event": "webhook.ping",
"id": "evt_6984986f56d12",
"timestamp": "2026-02-05T16:17:35Z",
"provider": "ROUTESTRIPE",
"api_version": "v1",
"data": {
"status": true
}
}If required, you may temporarily disable the webhook output by switching Status to Inactive.
Header Settings
Sensitive details. Never send your Secret to unauthorised actors or via non-secure channels. If you think the Secret has been compromised, use the corresponding function Secret → Regenerate to generate a new one.
X-Partner-ID in the webhooks' headers.How to use
Event Settings
Event Types Library
Visits
"visit.created" — Upon creating a visit manually or by import/API"visit.status.changed" — Upon visit status change"visit.delivery_note.changed" — Upon saving the recipient note"visit.recipient_note.changed" — Upon saving the courier note"attachment.signature.created" — Upon saving Signature attachment"attachment.photo.created" — Upon saving Photo attachmentBatch Structure
Even if the batch contains only a single event, RouteStripe always structures the "events"field as an array to ensure stability and scalability of your integration (unified processing, data integrity, efficiency).
Example structure for
"visit.created", "visit.status.changed", "visit.delivery_note.changed", "visit.recipient_note.changed" where "entity": "visit"{
"event": "batch",
"id": "bth_69834404dfe80",
"timestamp": "2026-02-04T16:05:08Z",
"provider": "ROUTESTRIPE",
"api_version": "v1",
"event_count": 1,
"data": {
"events": [
{
"entity": "visit",
"event": "visit.created",
"id": "evt_69834404dfe60",
"timestamp": "2026-02-04T16:05:08Z",
"object": {
"id": 172158,
"external_id": null,
"type": "D",
"route_id": 0,
"plan_id": 3451,
"name": "Visit 12",
"address": "",
"lat": "52.030187",
"lng": "4.307636",
"start_time": "08:00",
"end_time": "20:00",
"service_time": 5,
"status": 1,
"arrival_time": "",
"position": 0,
"label_position": 0,
"updated_at": "2026-02-04T16:05:08Z",
"created_at": "2026-02-04T16:05:08Z",
"deleted_at": null,
"package_capacity": "0.00",
"payment_status": 0,
"package_quantity": 0,
"package_load": "0.00",
"recipient_name": "",
"recipient_phone": "",
"recipient_note": "",
"delivery_note": "",
"polyline": "",
"distance": "0.000",
"completed_at": null,
"travel_duration": 0,
"waiting_time": 0,
"confirmation_type": "",
"signature_name": "",
"fail_reason_id": 0,
"confirmation_template_id": 0,
"source": 1,
"company_id": 7,
"source_id": null,
"warehouse_id": 0
}
}
]
}
}Example structure for
"attachment.signature.created" and "attachment.photo.created", where "entity": "attachment"{
"event": "batch",
"id": "bth_698343f4f1f51",
"timestamp": "2026-02-04T16:04:52Z",
"provider": "ROUTESTRIPE",
"api_version": "v1",
"event_count": 1,
"data": {
"events": [
{
"entity": "attachment",
"event": "attachment.photo.created",
"id": "evt_698343f4f1f3c",
"timestamp": "2026-02-04T16:04:52Z",
"object": {
"id": 305,
"visit_id": 172109,
"path": "attachments/7/0001/0001/72opJt6l8h8NwlpLj1ORNMPmIHIoHWBneO.jpg",
"type": "photo",
"updated_at": "2026-02-04T16:04:52Z",
"created_at": "2026-02-04T16:04:52Z",
"deleted_at": null
}
}
]
}
}Field Definitions
High level "event": "batch"
event — message type. The "batch" format is used. It allows grouping multiple events into a single request to reduce server load.id (with bth_ prefix) — unique ID of the specific request. Use it for logging and to prevent the repeated processing of the same package.timestamp — time of batch creation (UTC).provider — "ROUTESTRIPE" — data source marker.api_version — "v1" — data scheme version, allows your code to adapt to the API updates.event_count — amount of events per array. Can be used for a quick integrity check of "data" array events parsed.data — container field that holds the primary payload: the "events" array.Low level ("events" array objects)
event — specific event type. May be:"visit.created","visit.status.changed","visit.delivery_note.changed","visit.recipient_note.changed","attachment.signature.created","attachment.photo.created"id (with evt_... prefix) — unique event ID.timestamp — event time (UTC), signifies the time event factually occurred.object — contains a complete snapshot of the relevant domain object’s data at the time the event occurred. For visit and attachment objects, the full structure is included, identical to the response returned by a corresponding GET request to the API.Parameters of a visit’s "status" (System statuses and interface)
"status": 1 — Unscheduled"status": 2 — Planning"status": 3 — Scheduled"status": 4 — Done"status": 5 — FailedParameters of a visit’s failed execution "fail_reason_id"
"fail_reason_id": 1 — Not at the address"fail_reason_id": 2 — No answer to the call"fail_reason_id": 3 — Incorrect phone number"fail_reason_id": 4 — Incorrect address"fail_reason_id": 5 — Could not find the address"fail_reason_id": 6 — Refused"fail_reason_id": 7 — OtherParameters of a visit’s successful execution "confirmation_type"
"confirmation_type": "to_recipient" — Delivered to recipient"confirmation_type": "to_third_party" — Delivered to third party"confirmation_type": "to_mailbox" — Delivered to mailbox"confirmation_type": "to_save_place" — Leave in save place"confirmation_type": "to_door" — Leave at the door"confirmation_type": "to_pickup_point" — Delivered to pickup point"confirmation_type": "to_other" — OtherHandling Responses
200 OK (or any 2xx status code)400, 401, 403, or 404, RouteStripe will not retry delivery.Retry Policy
429 (Too Many Requests) or any 5xx server error.This results in a total elapsed time of 395 seconds (6 minutes 35 seconds) from the initial delivery attempt to the start of the final retry attempt.
Modified at 2026-03-30 15:19:31