Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk-java): document webhook signature checks in the README
Yudhi Armyndharis1b387951ed92
diff --git a/sdk/java/README.md b/sdk/java/README.mdindex c6de4bfe8..21288719f 100644--- a/sdk/java/README.md+++ b/sdk/java/README.md@@ -127,6 +127,33 @@ try {All extend `OpenWAError` (a `RuntimeException`). 503 is transient, but a catalog 503 can persist because WhatsApp may never answer that query, so bound any retry. A 429 from the global rate limiter lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and `retryAfterSeconds()` carries its `Retry-After` header. A 429 whose `code()` is `"SEND_PACING_LIMITED"` is not transient: do not retry it before `retryAfterSeconds()`, which then comes from the body and can be hours. `headers()` returns the response headers. A 503 does not prove a write was never carried out: the engine answers it when WhatsApp did not confirm in time, and the change may still have been applied, so re-read the state before repeating it. In a routed deployment a forward that fails before reaching the owner node answers 503, one that fails after the request reached it answers 502 or 504, and a 503 from the owner itself is relayed unchanged.+## 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 (a `byte[]`, or a `String` read as+UTF-8), 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+throws) for a missing, malformed or non-matching signature.+`com.rmyndharis.openwa.model.WebhookDelivery` types the parsed body.++```java+import com.google.gson.Gson;+import com.rmyndharis.openwa.WebhookSignature;+import com.rmyndharis.openwa.model.WebhookDelivery;+import java.nio.charset.StandardCharsets;++// In a servlet's doPost(request, response):+byte[] rawBody = request.getInputStream().readAllBytes();+if (!WebhookSignature.verify(rawBody, request.getHeader("X-OpenWA-Signature"), secret)) {+ response.setStatus(401);+ return;+}+WebhookDelivery delivery =+ new Gson().fromJson(new String(rawBody, StandardCharsets.UTF_8), WebhookDelivery.class);+// Process delivery.event() and delivery.data() here.+```+## Reliability & security- **Use HTTPS in production.** The API key is sent as `X-API-Key` on every