docs(chatwoot-adapter): correct the instance-mint setup path and add 401 troubleshooting (0.5.3) - #41
Merged
Conversation
…401 troubleshooting (0.5.3) The setup guide told operators to mint the integration instance from the OpenWA dashboard and paste the Chatwoot webhook secret there, but the dashboard's instance form has no secret field — it auto-generates one that can never match Chatwoot's, so every Chatwoot → OpenWA webhook delivery failed HMAC verification with a 401 (rmyndharis/OpenWA#821). Inbound kept working because it authenticates to Chatwoot's REST API with the apiToken, not through the webhook. - Setup now mints via the REST API, the only path that accepts a secret, with a full curl example and a warning against dashboard minting - State the concrete minimum Chatwoot version: v4.12.0, the first release with per-webhook secrets and timestamped webhook signatures (chatwoot/chatwoot#13573) - New Troubleshooting section maps the 401 symptom to its causes: secret mismatch, rotated secret, >300s clock skew, Chatwoot too old — and distinguishes 404 (wrong URL) from 401 (bad signature) Documentation only; no runtime code changed. Released as 0.5.3. Refs rmyndharis/OpenWA#821
Merged
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Fixes the setup documentation that led every dashboard-minted Chatwoot adapter instance into a state where outbound delivery (Chatwoot → WhatsApp) can never work, reported in rmyndharis/OpenWA#821.
Root cause (verified against both codebases): OpenWA verifies each Chatwoot webhook delivery against the integration instance's ingress secret (HMAC-SHA256 over
{timestamp}.{rawBody}). Chatwoot signs with its own per-webhook secret, which is auto-generated and read-only — it cannot be replaced with a custom value. But the OpenWA dashboard's instance-create form has no secret field, so it auto-generates a random secret that can never match Chatwoot's. Result: every webhook delivery fails signature verification with a 401, agent replies never reach WhatsApp, while inbound (WhatsApp → Chatwoot) keeps working because it authenticates to Chatwoot's REST API with the API token, not through the webhook.The previous setup guide made it worse: it told operators to "paste the Chatwoot webhook secret" in the dashboard — a step that is currently impossible to follow.
Changes
POST /api/integration/plugins/chatwoot-adapter/instances), the only path that accepts a caller-suppliedsecret, with a completecurlexample and an explicit warning against dashboard minting (including how to recover: delete + re-mint).Documentation only — no runtime code changed. Released as 0.5.3 (manifest + changelog + regenerated catalog included).
Verification
npm test— 401/401 passnpm run typecheck— cleannpm run catalog:check— no driftnode package.mjs chatwoot-adapter— v0.5.3 zip (11.1 KB) builds cleanlyRelated