Modaltrans can push events to your own HTTPS endpoint as they happen, so you do not have to poll the API or wait for a file. When something happens we send one signed POST with a JSON body. You return a 2xx and the delivery is done. Anything else counts as a failure, and failures that look temporary are retried for up to 22 hours.This page covers what is the same for every event type: how an endpoint is created, how to verify the signature, how to answer, what we retry and when an endpoint is switched off. What each event carries is described on its own page, starting with Tracking Webhooks.Setting it up#
Two sides are involved and it helps to be clear about who does what.The receiving side (your IT team, your software supplier, or your customer's) builds the address that accepts the deliveries and decides what that address is. Modaltrans never invents it.The Modaltrans side (a colleague with access to your Modaltrans settings) enters that address in Modaltrans, ticks the events and hands the signing secret back to the receiving side.Before the endpoint is created, the receiving address has to:be reachable from the public internet, and stay that way: no internal hostname, no private IP address, no VPN-only address. If the address later starts resolving to an internal address, deliveries stop and they are not retried;
answer over https with a valid certificate, since plain http is rejected when you save;
accept a POST with a JSON body and answer within 10 seconds, see Responding below.
1.
Go to Settings > Integration Settings > Webhook Endpoints and select New Webhook Endpoint.
2.
In Name, write who it belongs to, for example "Acme Ltd production". It is only a label for your own list.
3.
In Target URL, paste the address the receiving side gave you.
4.
Leave For a specific customer unticked and every event your account tracks is forwarded to that address, which is what you want for a system of your own. Tick it and pick the customer when the address belongs to one of your customers, and only that customer's events are sent.
5.
If the receiving side asked for a fixed header of their own, tick Send an extra authentication header and fill in the name and value they gave you, see An extra header of your own below.
6.
Under Subscribed Events, click each kind of record you need, for example Sea tracking event, and tick the events under it.
7.
Save. The endpoint page now shows the Secret. Send it to the receiving side the way you would send a password. Anyone who has it can forge a delivery.
8.
Select Send Test Event, pick one of the subscribed events, and have the receiving side confirm that the request arrived and the signature matched.
Verifying the signature#
Every request carries these headers:| Header | Value |
|---|
X-Modaltrans-Signature | sha256= followed by the lowercase hex digest |
X-Modaltrans-Delivery | Delivery id, identical on every attempt of the same delivery |
X-Modaltrans-Event | The event name, for example sea_tracking_events/create |
Content-Type | Always application/json |
User-Agent | Modaltrans-Webhook/1.0 |
Your signing secret looks like whsec_ followed by 32 random bytes in base64. Use the whole string, prefix included, as the HMAC key; do not strip the prefix and do not base64-decode it.Compute HMAC-SHA256 over the entire raw request body and compare the result, prefixed with sha256=, to X-Modaltrans-Signature. Sign the bytes exactly as received, before any JSON parsing or re-serialisation; whitespace matters. Use a constant-time comparison, not ==.You can check your implementation offline against this vector:secret whsec_SxQbP1Q6TTh9jC1zBDuvWJH0RGKiKpYcO0mQ4ap9ZmI=
body {"message":"You shall not pass!"}
signature sha256=d55e674078099a696aebbcb1c4e0094a938fd7902667c8d06de366bcdfcc2741
X-Modaltrans-Delivery.Some receivers sit behind an API gateway that rejects anything without a fixed header, before the request ever reaches the application. If that is your case, the endpoint can carry one extra header that we send on every request.Your Modaltrans administrator ticks Send an extra authentication header on the endpoint and fills in the name and the value you gave them. The value is yours, not ours: it is whatever your gateway already expects. If you have nothing set up yet, the button inside the value field generates a random 32-character key you can then configure on your side.A few rules, so the header is always a valid one:The name cannot be Host, Connection, Content-Type, Content-Length, Transfer-Encoding, User-Agent, Accept-Encoding or Expect, and cannot start with X-Modaltrans-. Those are ours, and overwriting them would break either the delivery or the signature.
The value has to be printable ASCII on a single line.
Spaces at either end are removed before saving, so a value pasted with a stray space still works.
X-Modaltrans-Signature as well.The endpoint page shows the header to your Modaltrans administrator; the request preview of each delivery masks the value.Responding#
Return a 2xx as soon as you have stored the body. Do not validate business rules, look up records or write to downstream systems before answering. If your processing fails after you have accepted the delivery, that is yours to retry; if you answer with an error we will resend the same body and you may end up processing it twice.A 2xx means "received", not "understood". Any other status is treated as a failure.Opening the connection may take at most 5 seconds. After that we wait 10 seconds for your answer, and the response body counts. A 200 whose body trickles in after that is a timeout on our side, and the same delivery is sent again, so answer first, answer completely, and do the work afterwards.We do not keep your response body when the delivery succeeds. When it fails we store the first 2 KB so your administrator can see the error you returned. We still download whatever you send before truncating it, so keep error bodies short and do not put anything sensitive in them.Retries#
| Outcome | What we do |
|---|
2xx | Done |
5xx, 408, 429, timeout, connection failure, TLS failure | Retried, up to five more times over 22 hours |
Other 4xx | No retry, the delivery is marked failed |
3xx | No retry, give us the final URL instead |
A delivery gets up to six attempts: the first one, then five retries.| Attempt | Roughly this long after the first attempt |
|---|
| 1 | Immediately |
| 2 | 15 minutes |
| 3 | 1 hour |
| 4 | 6 hours |
| 5 | 13 hours |
| 6 | 22 hours |
Each wait is counted from the attempt before it and is a floor, not a schedule: a retry can arrive a little later than the table says, never earlier, so do not time anything against it. The first 2xx ends the series. If the sixth attempt also fails, or an attempt fails in a way that is not retried, the delivery is marked failed and stays on the endpoint page, where your Modaltrans administrator can resend it; a resend starts a fresh series of six attempts.Test events are the exception: they are sent once and never retried, see Testing and troubleshooting below.Retries and manual resends reuse the stored body byte for byte, so X-Modaltrans-Delivery and eventID are identical on every attempt. The signature is the one exception: it is recomputed at send time, so it differs if the secret was rotated in between.When an endpoint is disabled#
Modaltrans keeps the time of the first failure in an unbroken run of failures, and every failed attempt counts, retries included. The run ends when a delivery succeeds, or when 24 hours pass without any failure; the next failure after that starts a new run. When an attempt fails while the run is already 24 hours old, the endpoint is disabled and the colleague who created it is notified.So an endpoint that works even once a day is never disabled this way, and neither is one that fails now and then with quiet days in between. A single delivery that fails all six attempts spans 22 hours, so it does not disable an endpoint on its own either; it takes failures that keep coming for a full day.While an endpoint is disabled, new events are not queued for it. They are skipped, not stored, and they do not arrive later. Retries that were waiting are not sent either: those deliveries are marked failed and stay on the endpoint page. A manual resend still goes out, once. Someone has to set the endpoint back to active by hand once the problem is fixed. After that, Resend Failed on the endpoint page sends the failed deliveries again in one go, see Testing and troubleshooting below. The events that were skipped while the endpoint was disabled have to be asked for separately.Identifiers and ordering#
Two identifiers do different jobs:eventID identifies this message. A correction to something you already have arrives as an update event with a new eventID.
modaltrans.eventKey identifies the record as Modaltrans holds it. It stays the same while that record stays the same, so upsert on it. What can make it change is specific to the event type, and the event page says so.
X-Modaltrans-Delivery tells you whether two requests are the same attempt at the same message. It is stable across retries and manual resends, so use it to avoid double-processing, but do not treat a repeat as something to ignore silently: a resend usually means your administrator wants that event applied.Deliveries are not ordered, and eventCreatedDateTime is the moment we built the message, not the moment anything happened. A create and the update that follows it can carry the same value, so it settles nothing on its own. Apply messages in the order you receive them and let the last one win for a given eventKey.data is an array today and always holds one element. If we start grouping several events of one shipment into a single delivery, the shape will not change.Testing and troubleshooting#
Your Modaltrans administrator can send a test event at any time: Send Test Event on the endpoint page lists the events the endpoint is subscribed to. The test delivery is signed and headed exactly like a real one and carries "test": true in the envelope, so you can drop it before it reaches your records. Its body has one field real payloads never have, modaltrans.sentBy, so do not reject it on a strict schema check. A test event is sent once and never retried, so a test that fails is marked failed straight away; fix the receiving side and select Resend on it.The same page lists the endpoint's deliveries, newest first and ten to a page, under three tabs:Failed: deliveries that will not be tried again, with their number next to the tab.
Will retry: deliveries waiting for another attempt. Attempts shows how far along they are, for example 2 / 6, and Next attempt shows when the next one is due.
Modified at 2026-11-02 12:51:34
