Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(webhooks): return false from the signature check on a bad header

Yudhi Armyndharisdffdef3ed1b8
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index 9b70b748e..d04caeff0 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -363,10 +363,14 @@ function signPayload(payload: object, secret: string): string {
}
// Client: Verify signature
-function verifySignature(payload: string, signature: string, secret: string): boolean {
+function verifySignature(payload: string, signature: string | undefined, secret: string): boolean {
+ if (typeof signature !== 'string') return false;
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(payload).digest('hex');
+ const a = Buffer.from(signature);
+ const b = Buffer.from(expected);
- return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+ // timingSafeEqual throws on a length mismatch, so a short or forged header must return false first.
+ return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 3f7b8cdbb..18f471a2d 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -7021,11 +7021,17 @@ The hex is an HMAC-SHA256 computed over the **raw JSON request body** (exactly t
const crypto = require('crypto');
function verify(rawBody, header, secret) {
+ if (typeof header !== 'string') return false;
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
- return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
+ const a = Buffer.from(header);
+ const b = Buffer.from(expected);
+ // timingSafeEqual throws on a length mismatch, so a short or forged header must return false first.
+ return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```
+Complete Express and FastAPI receivers are in [`examples/webhook-signature-verification.md`](examples/webhook-signature-verification.md).
+
If no `secret` is configured the `X-OpenWA-Signature` header is omitted entirely.
### Idempotency & delivery headers