Reseller-style partners can link their users to authorised Sendle tracking pages. These special, authorised pages let your users access tools for managing orders, and also see extended order information.
With these links users can self-serve common support tasks, depending on their role in the transaction. This provides users a similar support experience to the one they'd receive if they booked a parcel via the Sendle Dashboard. These support tools are important as they:
- Provide users with common tools at their fingertips, improving their experience.
- Collect required information before a support ticket is opened, speeding up resolution.
- Funnel support requests about the parcel to Sendle, reducing the load on your team.
- Let us update processes and launch new order tools without changes or development needed on your side.
Authorised Tracking Pages also offer more detailed information compared to the standard tracking pages. Public tracking pages don't expose sensitive details such as sender & receiver information, addresses, pickup locations, or agent addresses.
These pages are accessed via cryptographically signed links that are generated by your integration. They do require development work to implement, but end up reducing a lot of support and operational overhead.
If you choose not to integrate the Authorised Tracking Pages, users will need to sign up or claim their account on Sendle.com to be able to access the full suite of tools.
We recommend linking to the authorised tracking page wherever the sender/receiver would normally see the Sendle Reference. This can be in your app, on web pages, or in emails sent to those users.
When adding these links, make sure you're sending the right token (
receiver) to the right user.
Here are the tools users can access, depending on their role in the order.
Some tools are optional and can be disabled depending on how your account is configured. This is useful when an action may interfere with your internal processes or be a fraud risk. If you'd like us to disable certain tools on your authorised tracking pages, let your partnerships liaison know.
|Cancel Order (before transit)
|Available at any time to open a ticket regarding this order.
|Allows selecting a new pickup date for the existing order.
|Reschedule Pickup (Futile)
|Required for a Sender to schedule another pickup in case of a Futile Pickup.
|Edit Pickup Instructions
|Available in case of a Futile Pickup.
|Useful to confirm delivery in areas with inconsistent tracking, such as International parcels.
|Late Parcel Enquiry
|Only available past ETA.
|Missing Parcel Enquiry
|Available once an order is marked as Delivered.
|Available once an order is marked as Card Left or Unable to Deliver.
|Damaged Parcel Claim
|Available once an order is marked as Delivered or Damaged.
|Available once an order is marked as Lost and an investigation has been deemed eligible for claim.
Authorisation is handled by embedding a JSON Web Token (JWT) in a tracking page URL. These tokens are created and managed by you, and are signed using a secret encryption key you control.
We verify the token's signature and authorise access to the tracking page for the user. If we are unable to verify the token's signature then we fall back to displaying the public tracking page for the order.
A JWT-enabled tracking link must contain the
ref parameter, and the JWT embedded as the URL fragment:
https://track.sendle.com/tracking?ref=<sendle reference>#<JSON web token>
The JWT contains the Sendle Reference, as well as the intended role of the user accessing the tracking page (
It is not possible to use these keys or JWTs with our Sandbox.
For testing, we recommend creating and cancelling a drop-off test order on your production account, and then accessing that page using a production JWT. Using drop-off rather than pickup will make sure a driver isn't dispatched to collect the order.
We use ES256 for signing token payloads. This employs the Elliptic Curve Digital Signature Algorithm (ECDSA) using the P-256 curve and the SHA-256 hash algorithm.
Before you can sign tokens, you must first generate a signing keypair. A keypair is made up of a private key and a public key.
- You use the private key to sign tokens. This key is secret and should be kept out of version control.
- The public key what we use to verify your tokens' signatures. This key is public and can be sent over email or stored in version control.
This console command will generate a private key called
$ openssl ecparam -name prime256v1 -genkey -noout -out sendle_private.pem
$ cat sendle_private.pem
-----BEGIN EC PRIVATE KEY-----
-----END EC PRIVATE KEY-----
This console command will generate a public key derived from the private key:
$ openssl ec -in sendle_private.pem -pubout -out sendle_public.pem
$ cat sendle_public.pem
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
Email your public key to [email protected]. Your private key must be kept secret, do not send it to us. Once we have imported the public key we will send you a corresponding key ID. This ID must be included in all JWT headers as
Periodically rotating encryption keys helps mitigate the risk of a compromised key. Multiple active keys are allowed, which means that you can migrate to a new key at your own pace.
Simply generate a new keypair and send us the public key. When you're ready to invalidate the old key, just let us know.
If you suspect a private key has been compromised, generate a new key pair and send us the new public key, along with the compromised
kid. We will invalidate the old one as soon as possible.
All header parameters are required:
kid: the ID of your supplied public key.
alg: the signature algorithm. Must be set to
ref: the order’s Sendle Reference.
role: the user role that should be authorised. This must be either
jti: a unique value that identifies the token. Using a UUID is recommended but not required.
iat: the token creation time. This should be represented as a Unix timestamp.
exp: the expiration time of the token. This should be represented as a Unix timestamp.
Token contents are signed cryptographically to prevent tampering. All tokens must be signed using the ES256 algorithm. Tokens signed with any other algorithm will not be valid.
Your private key is the only thing that's required to create valid tokens and management links for your users' orders. As such, it is vital that your private key is kept secret. If you suspect that a key has leaked, please contact us immediately.
Ensure that you are not saving JWTs to any services that track outbound clicks such as Google Analytics. If you suspect that an individual JWT has been leaked, simply regenerate it and contact us with the compromised token's ID (
We recommend generating JWTs on the fly rather than persisting them to a datastore. It will be much easier to rotate or invalidate encryption keys when you don’t have to bulk-update persisted tokens.
Updated 8 months ago