Integration Guide:
Custom Email/SMS Invites for Real Time Tracking

This guide explains how to integrate real-time tracking invitations for consignees. It ensures timely, accurate notifications that drive engagement with the tracking user interface.

Prepare Data Integration

Providing real-time tracking-specific details during the data ingestion process is mandatory.

Configuration

Copy
Copied
{
  "enabled": true,
  "notification": { /* Set all fields to false to disable notifications from Bettermile */ },
  "redirect": { /* Configuration details provided below */ } 
}

Full Documentation of Fields

The realtimeTracking (RTT) object contains additional configuration data required specifically for Better Tracking services.

Name Mandatory Description
enabled no true/false: enables/disables RTT for the specific job. If a tenant is using RTT, the default is true, otherwise RTT will not be enabled anyway.
notification no Notification details for this job. See Notification below.
redirect no Real-time Tracking parcel redirect options for example depending on service type. Contains the attributes neighbor, deposit and parcelShop to set permissions for this job, wether the delivery may ad-hoc be redirected to a neighbor or be deposited at a consignee location or be handed over to a parcel shop.
Example:
"redirect" : {
  "neighbor": true,
  "deposit": false,
  "parcelshop": true 
}

Defaults: false for all fields.

Notification

Describes how and when to contact the consignee via Real-Time Tracking.

Name Mandatory Description
invite no How to send the “Invite” to the consignee. Contains the attributes email and sms (true/false) to define whether or not to send invite messages via these channels.

Example:

"invite": {
    "email": true,
    "sms": false
  }
reminder no How to send the reminder to the consignee. Contains the attributes email and sms (true/false) to define whether or not to send reminder messages via these channels.

Example:

"reminder": {
    "email": true,
    "sms": false
  }

Webhook Integration

Parcel tracking availability is communicated using a webhook “push” approach. We send requests to an HTTP endpoint (the webhook) that you provide.

Preparing to receive a Webhook Notifications

As prerequisite of Bettermile enabling to send you Webhook notifications, you must make sure you are prepared to receive them:

  • You will need to implement an HTTPS endpoint to receive POST requests as a JSON payload that include the event objects. (please share the endpoint URL with the Bettermile team)
  • For each request received from Bettermile, your endpoint needs to answer with a 2xx status code.
  • Bettermile will not transfer any data on unsafe connections. So please, ensure your created endpoint is both public, and can handle HTTPS connections. We accept endpoints with self-signed keys. (To be provided by you.)

Event types

You should only get from the events you receive the important fields for your logic to work. You also should ignore any events not important for your use case. Parsing or checking the data on fields and events you don't need may put undue stress on your side.

Delivery attempts

If your endpoint is down or not responding with a 2xx code, Bettermile will keep retrying the delivery of the messages by around an hour. The retries have an exponential backoff independent for each message.

After the 1-hour period is over, Bettermile will stop trying to deliver the message and discard it. Due to the fast nature of delivery events we consider 1 hour to be enough time for the message to still be relevant and be retried.

Handling the Events

Due to the distributed nature of our internal systems, there may be some edge cases happening.

Out Of Order Delivery

The delivery of the messages to your endpoint may come out of order from the actual order the events themselves occurred. If ordering is important for your internal systems, you should set up a system to handle this case. We strongly recommend you don't do that though. It may put undue strain on your systems to order the messages you receive. We recommend you project a system as stateless as possible to prevent unforeseen edge-cases.

Duplicate Delivery

Some messages may be delivered more than once, though rare, this can happen. Thus, we recommend your systems are able to handle the received messages in an idempotent manner. One way to do this is storing the events you received and if you receive one that is already stored, you may discard it and answer with a 2xx code.

Secure connections

Bettermile will outright refuse any non-encrypted connection. So be sure that HTTPS is enabled on your endpoint, even if with a self-signed key.

Redirects and other HTTP statuses

Bettermile will consider any status different from 2xx statutes an error. This also means Bettermile will not follow any redirects, considering a redirect status an error, and will keep retrying until the status is 2xx or the retry window expires.

Non-Functional Requirements

  • Ensure 99.9% uptime and processing of webhook events within 500 milliseconds to avoid piled-up messaging queues that would delay invites to consignees
  • Industry incident management best practices including monitoring, alerting, and duty shifts during peak times

Example Payload

Copy
Copied
{
    "createdat": "2025-01-01T01:00:00.123456Z", 
    "parcelnumber":"D11223344",
    "tenantid":"gls-de"
}

Track Performance Metrics

  • Use UTM parameters in invite links to track and compare channel performance.
    • Email: utm_source=invite-email
    • SMS: utm_source=invite-sms
  • Optimize: Adjust content or channels based on performance insights.