Webhook secrets should authenticate the sender without appearing in request logs or client code. Verify the provider’s supported signature scheme before processing the event, then keep replay and duplicate handling separate from authentication.
Webhook trust begins at ingress
A webhook receiver accepts externally delivered events that can change call or business state. Sender verification, payload validation, event freshness, and duplicate protection address different threats and failure modes.
For a proposed implementation, retrieve credentials from a protected server-side secret store and scope them to the relevant provider account. Verify the exact payload representation required by that provider before modifying or parsing it in a way that breaks signature validation.
Do not invent a generic signature algorithm for every service. Consult the selected provider’s current official documentation and test with its supported fixtures or tooling before writing executable integration code. This article provides a design checklist rather than an untested code sample.
Test a fictional forged transfer event
An attacker submits a request claiming that a staff member accepted a transfer. Without sender verification, the application might connect or release the wrong call leg. A valid-looking event body is not proof that the provider sent it.
After signature verification, the receiver still checks that the event references a current attempt and permitted account. A genuine delayed event can be stale, and a genuine repeated event can otherwise trigger duplicate work.
| Ingress case | Required handling |
|---|---|
| Invalid sender signature | Reject without state mutation |
| Valid signature, malformed payload | Safe validation failure |
| Valid event for wrong account | Deny the account boundary |
| Repeated event | Idempotent processing |
| Late acceptance for expired attempt | Preserve the current transfer state |
Test log output during both accepted and rejected requests. Debug middleware may capture authentication headers or raw payloads even when application logs are carefully minimised.
Rotate credentials without losing control
Document who can read, replace, and revoke webhook credentials. If the provider supports overlapping keys, use its documented transition method. Validate both normal delivery and rejection of retired credentials under the supported rotation plan.
Secrets in URLs can leak through proxies, analytics, and support screenshots. Prefer the provider’s approved verification method and minimise sensitive request capture. Do not treat transport encryption as proof of sender identity or replay protection.
This ingress design is proposed. The voice platform case study describes related integration work. Pair it with trace redaction and safe tool retries.
Webhook secret FAQ
Is an obscure endpoint URL sufficient authentication?
No. Use the selected provider’s supported sender-verification mechanism.
Does a valid signature make the event current?
No. Apply the provider’s supported freshness checks and your operation-state rules.
Should failed requests include raw headers in logs?
Avoid exposing credentials. Retain safe error categories and diagnostic references instead.