Verifying It's Really Them
The address Vera registered with Tandem is a door that opens onto the public internet, and a door that anything can knock on. A message claiming "event": "ride.completed" is a few lines of text, and Chapter 3 taught exactly how easy those are to type: anyone who knows the address can send one that looks perfect.
So before the office acts on a delivery, one question has to be answered: did Tandem really send this? The Tandem-Signature header from the last page is the answer, and the idea behind it will outlive every product named in this book.
Anyone Can Knock
Start with the threat stated plainly, because it is less dramatic and more common than people expect. The webhook address is a URL. URLs get written down: in server logs, in screenshots, in tickets, in the browser history of whoever set it up, and sometimes in a pattern guessable from the outside. Once it is known, sending a request to it takes one command.
What a stranger could then do is not exotic. Post phantom completed rides, and the Thursday report acquires trips that never happened. Post enough of them and the city's rebalancing crews get sent somewhere pointless. Nothing was hacked, nothing was broken into — a public door simply accepted what was pushed through it, exactly as it was built to.
This is not paranoia. It is the standing condition of every address open to the internet, and it is the reason providers sign what they send rather than trusting the address to stay secret.
The Shared Secret
When Vera registers the endpoint, Tandem also gives her a signing secret: a long random string that only the two sides know. It is a credential in exactly the sense Chapter 5 taught, so it gets Chapter 5's treatment — the password manager, never a chat message, never a screenshot, and rotated the moment there is any doubt.
Tandem then uses that secret to compute a signature for every delivery: a short value derived from the exact body, the timestamp of sending, and the secret itself. Change one character of the body and the signature comes out different. Compute it without the secret and you cannot produce the right value at all. That value travels in the Tandem-Signature header, next to the timestamp it covers — and the timestamp is not decoration: a genuine delivery someone captured could otherwise be re-sent later and would still verify, so receivers also refuse deliveries whose timestamp is too old.
Think of the wax seal on an old letter. Anyone can read the letter, and anyone can write a convincing one — but only the person holding the seal can press that particular mark, and the mark breaks if somebody opens the letter and rewrites it along the way. A beautifully written letter with a broken seal is more suspicious than a plain one, not less.
Checking It
Verification is the mirror image, and it happens on Vera's side. The receiving tool takes the body that arrived and the secret it holds, computes the signature the same way Tandem did, and compares the two values.
If they match, two facts follow at once. The sender holds the secret, which means it is Tandem. And the body has not been altered since the signature was made, because any change would have broken the match. If they do not match, the correct behavior is unglamorous: discard the delivery, write a log line saying one arrived and failed, and act on nothing. If failures keep coming, that log is what Jonas needs to see.
The arithmetic itself is not the reader's job, and this page deliberately stops short of it — the receiving tool or the developer's library does the computing, and the settings screen usually offers one field for the secret and one switch marked something like "verify signatures". Your job is to know that the switch exists, that it is worth nothing while it is off, and why the whole thing is there. The mathematics under it is a proper subject with a proper home: this catalogue covers it in Security for Beginners, and in more depth in the CyberSecurity Deep Dive.
The Idea Travels
Signing a message with a shared secret and checking it on arrival is not a Tandem invention, and recognizing the pattern is most of what this page is for. Every serious provider that sends webhooks has a header of its own with the same job under a different name, and the documentation always describes how to verify it.
The same idea shows up away from webhooks too. Signed download links that stop working if anyone edits the address, receipts a system issues to itself, messages passed between two halves of a company's own software: all of them are sign-then-verify, and all of them answer the identical question. Who really sent this, and did it arrive unchanged?
- "My endpoint uses https, so the sender is already proved." HTTPS protects the channel: nobody read or altered the message on the way. It says nothing about who started it, and any stranger can speak https to a public address. Channel and identity are two different locks on two different doors.
- "Nobody knows my webhook address, so nothing can reach it." Addresses leak, exactly as keys do — logs, screenshots, guessable patterns. Obscurity buys you a delay of unknown length. A signature is a proof, and it does not expire when somebody forwards an email.
- "A payload that looks valid probably is." Looking valid is free. You built valid-looking JSON by hand in Chapter 3 with no special access at all. The signature is the part of a delivery that cannot be produced from the outside.
- "Verification is the provider's responsibility." Tandem signs; only the receiver can check. A provider that signs every delivery and a receiver that never looks are, in practice, exactly as safe as no signature at all.
- Unverified webhook endpoints are a common, boring, entirely real weakness. "Is signature verification turned on?" is now a question you can ask of any integration at work, and it is a question that tends to get a nervous answer.
- Channel versus identity is a distinction that reaches far past webhooks. It costs one page here, and it is usually learned the other way: from an incident report.
Knowledge Check
What does the signature prove that https alone does not?
- That the message could not be read by anyone along the way
- Who sent the message, and that its body was not changed
- That the message was delivered exactly once, in the right order
- That the event it describes genuinely happened at Tandem
A delivery arrives whose signature does not match. What is the correct response?
- Process it anyway if the body looks plausible, then investigate
- Discard it, log it, and tell Jonas if it keeps happening
- Ask Tandem to send the same delivery again with a new signature
- Switch verification off until the mismatches stop appearing
How should the signing secret be handled?
- Published with the endpoint address so senders can use it
- Shared with any tool that needs to read the delivery bodies
- Like any other credential: kept in a vault, rotated on doubt
- Kept in a note next to the endpoint settings for convenience
What can a stranger who learns the webhook address do to an endpoint that never verifies?
- Feed it invented events that it will treat as genuine news
- Read the rider records held behind Tandem's partner API
- Sign in to Tandem's partner dashboard as the city office
- Intercept the genuine deliveries before they arrive
You got correct