ENGINEERING NOTE 31 / 50 · CARD
Verify payment webhooks before trusting their contents
A JSON payload that looks valid is not evidence of its sender. Verify the provider’s documented signature over the required bytes before applying financial effects.
Published by OPEN RAMBO. The engineering patterns and pseudocode illustrate designs, not a documented product API. Numerical examples are illustrative.
Preserve the signed bytes
Some protocols sign the raw body. Parsing and reserializing JSON can change whitespace or field order and break verification. Configure body handling at the webhook route and test it with exact fixture bytes. Do not invent a signature format from an example.
Apply replay controls
Where the protocol includes a signed timestamp, enforce its documented tolerance. Deduplicate event identifiers independently of timestamp checks. A valid recent signature can still accompany a repeated event and must not cause a second credit.
Rotate secrets carefully
Use a controlled overlap only if supported by the protocol, with separate key identifiers and removal dates. Keep secrets out of logs, browser bundles and support screenshots. Record verification failure categories without storing the secret or sensitive payload.
Illustrative implementation
raw = request.raw_body
verify_documented_signature(raw, headers, active_keys)
deduplicate(event_id)
apply_business_effect_once()Acceptance check
Test one altered byte, an expired timestamp, a repeated valid event and an unknown key. Each must follow the intended rejection or deduplication path.