fix(security): migrate webhook auth to HMAC-SHA256 signature header (#970)

.env.example

@@ -98,6 +98,19 @@ TELEGRAM_BOT_TOKEN=...
 HTTP_HOST=0.0.0.0
 HTTP_PORT=8080
 HTTP_WEBHOOK_SECRET=your-webhook-secret
+# Webhook authentication uses HMAC-SHA256 signature verification.
+# Callers must send an X-IronClaw-Signature header with format: sha256=<hex_digest>
+# where the digest is HMAC-SHA256(HTTP_WEBHOOK_SECRET, raw_request_body) in lowercase hex.
+#
+# Example (bash):
+#   BODY='{"content":"hello"}'
+#   SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$HTTP_WEBHOOK_SECRET" | cut -d' ' -f2)
+#   curl -X POST http://localhost:8080/webhook \
+#     -H "Content-Type: application/json" \
+#     -H "X-IronClaw-Signature: sha256=$SIG" \
+#     -d "$BODY"
+#
+# DEPRECATED: Passing "secret" in the JSON body still works but will be removed in a future release.
 
 # Signal Channel (optional, requires signal-cli daemon --http)
 # SIGNAL_HTTP_URL=http://127.0.0.1:8080