Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): document webhook signature checks in PHP and Python READMEs

Yudhi Armyndharis15890851cd16
diff --git a/sdk/php/README.md b/sdk/php/README.md
index 7a5892566..c5fb481e9 100644
--- a/sdk/php/README.md
+++ b/sdk/php/README.md
@@ -84,6 +84,25 @@ try {
}
```
+## Receiving webhooks
+
+A webhook configured with a secret signs each delivery in its `X-OpenWA-Signature` header. Check it
+with `WebhookSignature::verify` against the raw request body, exactly as received, and decode the
+JSON only after the check passes: a re-encoded body can differ byte for byte and will not verify.
+The helper returns `false` for a missing, malformed or non-matching signature.
+
+```php
+use OpenWA\WebhookSignature;
+
+$raw = file_get_contents('php://input');
+if (!WebhookSignature::verify($raw, $_SERVER['HTTP_X_OPENWA_SIGNATURE'] ?? null, $secret)) {
+ http_response_code(401);
+ exit;
+}
+$delivery = json_decode($raw, true);
+// Process $delivery['event'] and $delivery['data'] here.
+```
+
## Notes
- **Use HTTPS in production** — the API key is sent as `X-API-Key` and is bearer-equivalent.
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 09db2acd9..bc1fdab76 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -108,6 +108,34 @@ except OpenWANotFoundError as e:
- Escape hatch for endpoints the SDK does not wrap:
`client.request(method, path, query=…, body=…)`.
+## Receiving webhooks
+
+A webhook configured with a secret signs each delivery in its `X-OpenWA-Signature` header. Check it
+with `verify_webhook_signature` against the raw, unparsed request body (`bytes` or `str`), exactly
+as received, and parse the JSON only after the check passes: a re-serialized body can differ byte
+for byte and will not verify. The helper returns `False` (never raises) for a missing, malformed or
+non-matching signature. `WebhookDelivery` (in `openwa.types`) types the parsed body.
+
+```python
+import json
+
+from flask import Flask, request
+from openwa import verify_webhook_signature
+from openwa.types import WebhookDelivery
+
+app = Flask(__name__)
+
+
[email protected]("/openwa/webhook")
+def openwa_webhook():
+ raw_body = request.get_data()
+ if not verify_webhook_signature(raw_body, request.headers.get("X-OpenWA-Signature"), secret):
+ return "Invalid signature", 401
+ delivery: WebhookDelivery = json.loads(raw_body)
+ # Process delivery["event"] and delivery["data"] here.
+ return "OK", 200
+```
+
## Releasing
Publishing to PyPI is done by the