A webhook is used to notify your internal system of RouteStripe events in real time. The updated data is sent via a POST request containing a JSON events array to your Callback URL.

How it Works

When the RouteStripe event occurs, it is sent to the endpoints previously registered and configured for the corresponding event type. After your system receives the POST request, the events are handled and utilised according to your internal logic.

Webhook Security

To ensure the data originates from RouteStripe and has not been tampered with during transfer, each request includes a digital signature in the X-Signature header.

How Verification Works

The signature is generated using HMAC-SHA-256. The raw body of the request is used as a message, and your unique Secret is used as the key.

Verification Steps

Receive the header: Save the X-Signature value.
Receive the raw body: Using the original JSON string (not the object) that was received via POST.
Calculate the hashsum: Create a HMAC SHA-256 hash of your own using your Secret (UTF-8) and Raw Body received.
Compare the values: If the hashsum you have calculated equals the hashsum of the header — the request is authentic.

N.B. If hashsums are unequal ignore the request and return 401 Unauthorized HTTP status to protect your system from non-certified data.

How to Set Up

Path: RouteStripe → Company → API

Go to RouteStripe → API, Webhook section. Click “Add Webhook” and fill in the details.

Basic Information

Callback Url — your endpoint that receives the events
Description — your description

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

Secret — is your unique key that is used to confirm the webhooks are sent by RouteStripe. It is automatically generated upon the webhook-endpoint creation.

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.
Partner ID — non-mandatory ID that allows connecting RouteStripe data from your internal accounting system. If set up, RouteStripe will return X-Partner-ID in the webhooks' headers.

How to use
- Routing: Use this header at your gateway to route the webhook to the target server or database without parsing the JSON payload.
- Secret instant search: Look through your database and immediately locate the Secret for signature verification.

Event Settings

Select the events you want to process for the endpoint you are setting up.

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 attachment

Batch Structure

When an event occurs, the JSON payload containing an array of events will be sent to your endpoint.

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

Our webhook payload employs a two-level structure. This design cleanly separates delivery metadata (e.g., webhook ID, timestamp, signature) from the actual event data.

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 — Failed

Parameters 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 — Other

Parameters 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" — Other

Handling Responses

Upon receiving a webhook, your server must confirm successful data receipt by returning an appropriate HTTP status code.

RouteStripe considers delivery successful when it receives:

HTTP Status Code: 200 OK (or any 2xx status code)

For responses with HTTP status codes 400, 401, 403, or 404, RouteStripe will not retry delivery.

Retry Policy

Retry attempts are triggered if:

Your server fails to respond within 20 seconds, or
Your server responds with status code 429 (Too Many Requests) or any 5xx server error.

Retries follow an incremental backoff schedule with the following delays after each failed attempt:

+5 seconds
+30 seconds
+60 seconds
+300 seconds

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.

💡
Note
After 5 consecutive failed delivery attempts (initial attempt + 4 retries), RouteStripe will cease further retries for that webhook event and send an email notification to the user specified in the Owner field (Company → General). The email details the integration issue and includes the configured Callback URL. This notification is sent once per day, scheduled at the time of the first incident occurrence.