The webhook that announces a signed quote posts the prices, the discounts and the buyer’s email to a URL somebody typed into a settings page a year ago. One shared secret vouches for all of it. Request that same quote from the API and you need a bearer token with the right scope, the quote has to belong to your account, and the read lands in the access log.
That’s the same data held to two standards. I think the API has the right one, and the sender is the side that can close the gap, because the sender decides what goes into the request and where the request goes.
This is the review I’d run on any system that sends webhooks. Twelve points in four groups.
Send an id and keep the data behind the API
- The payload carries an event id, a type, a timestamp and the id of the object. No prices and no emails.
- The receiver gets the details by calling the API with its own OAuth 2.0 access token, so scopes, account checks and revocation cover webhook data too.
- One piece of code builds the payload from an explicit field list. Nothing serializes an internal event straight onto the wire.
Point 3 is about where these events start. In a CRM stack the trigger is often a Salesforce platform event or a Change Data Capture message, and those carry changed fields, sometimes most of a record. On an internal bus that’s useful. Forwarded as is to a partner URL, it’s a data export nobody approved.
The price is a second request per event, and a receiver that has to hold API credentials. I’ll pay that every time. If a thin notification lands in the wrong place, the reader learns that a quote with some id was signed.
{
"id": "evt_01HW9Q4T7MZ3K8R2VXN5",
"type": "quote.signed",
"created": 1748131200,
"data": { "quote_id": "qt_48213" },
"links": { "quote": "https://api.thornbury.example/v1/quotes/qt_48213" }
}
Check where it’s going, every time
A customer-supplied URL turns your delivery workers into an HTTP client that anyone with access to a settings page can aim. Aimed inward, that’s server-side request forgery.
- Endpoints are https on port 443 with no credentials in the URL, and the host is on the allow-list of domains the partner registered.
- At delivery time, resolve the hostname and refuse loopback, private and link-local addresses, including the cloud metadata address 169.254.169.254. Then connect to the address you checked, not to a fresh lookup.
- Don’t follow redirects. A 301 counts as a failed delivery and a note to the endpoint’s owner.
Checking at registration isn’t enough. DNS records change, and a host that pointed at a partner’s load balancer in March can point at 10.0.0.5 in May. The check belongs in the delivery path, on every attempt and ahead of the signer, so nothing gets signed for a destination you wouldn’t send to.
One secret per endpoint, and a timestamp in the signature
- Every endpoint has its own secret: 32 random bytes, shown once, stored encrypted.
- The signature covers the event id, the send time and the raw body, and receivers are told to reject anything older than five minutes.
- Rotation runs with two live secrets and has a deadline.
A secret shared across a partner’s endpoints means the config file on their test server can forge events for production. And a signature with no timestamp stays valid forever, so anyone who captures one request can replay it next month.
The scheme is plain HMAC, the construction from RFC 2104, with SHA-256:
Headers on every delivery
Webhook-Id: evt_01HW9Q4T7MZ3K8R2VXN5 same value on every retry
Webhook-Timestamp: 1748131200 Unix seconds, set when this attempt is sent
Webhook-Signature: v1=<hex> two v1 entries, space separated, during rotation
Signed string
<Webhook-Id> "." <Webhook-Timestamp> "." <raw request body bytes>
Signature
hex( HMAC-SHA256( endpoint_secret, signed_string ) )
Receiver
1. Reject if |now - Webhook-Timestamp| > 300 seconds.
2. Build the signed string from the raw body bytes, before any JSON parsing, and compute the HMAC.
3. Accept if it equals any v1 entry, compared in constant time.
4. If this Webhook-Id was already processed, answer 200 and do nothing else.
Rotation with two live secrets
1. Create secret B for the endpoint. Secret A stays active.
2. Send both: Webhook-Signature: v1=<sig with A> v1=<sig with B>
3. The partner deploys B. Either entry passes, so no delivery fails.
4. The partner confirms in settings, and A is deleted.
5. With no confirmation, A is deleted after 7 days anyway.
Step 5 is the deadline from point 9. Without it, “two live secrets” quietly becomes the permanent state.
Thornbury Quotes and the test server
Thornbury Quotes is a company I invented for this post. It sells quoting software, and its quote.signed webhook used to carry the whole quote. One partner, while debugging, pointed its production endpoint at a test server and forgot to point it back. For a while every signed quote for that partner’s customers landed on a machine with a shared login and request logging turned on.
Nobody attacked anything. The signature was valid and the deliveries returned 200, which is why it went unnoticed.
Thornbury’s fix is the payload above. It’s about 180 bytes on the wire and it holds one id. The partner’s handler fetches the quote with its own token, scoped to read quotes for the accounts it serves. Now the same mistake leaks a list of ids. The test server has no token, so the fetch-back never happens from there, and a signed quote that nobody fetched within the hour raises an alert on Thornbury’s side.
Operate it like the API
- The delivery log records event id, endpoint, resolved address and status. It doesn’t store the body.
- Adding or changing an endpoint needs an admin role, lands in the audit log and emails the account owners. An endpoint that fails for several days is disabled.
- A retry keeps the event id and gets a fresh timestamp and signature, so the replay window never rejects a legitimate retry and the receiver can still deduplicate. I wrote up the receiving half of that in the inbox table post.
The fetch-back also gives you a record that push never could. With fat payloads, “who read quote qt_48213 last month” has no answer on your side; you know what you sent and nothing about who opened it. With thin ones it’s a query against the API access log, by token.