[Sealdot]

Problem

Webhook consumers can calculate a different digest by signing only the body, reserializing JSON, or using an API/contact identity token instead of the source's webhook signing secret. The API introduction does not link to receiver verification guidance.

Related: chatwoot/chatwoot#13809. This documentation change does not claim to fix or close that report.

Solution

Add a webhook verification guide to API Reference navigation and link it from the API introduction. Include a standard-library Python example, timestamp-plus-original-body signing input, source-specific secrets, and separate replay/idempotency guidance. The branch is synchronized with the current documentation configuration, retaining upstream GA4 settings.

Key decisions

• Scope source mappings explicitly to v4.17.1, with links to the listeners and signing implementation; older installations may differ.
• Label the example's age/skew window as receiver policy.
• Explain that the delivery header is outside the signed input and is not an authenticated logical-event identity.
• Keep this contribution limited to documentation; no runtime or customer-service behavior changes.

Tests

• Extracted and executed the Python example: 19 checks covering original UTF-8/newline bytes, tampering and JSON reserialization, wrong key/timestamp, age/skew boundaries, malformed headers, and non-finite clocks. Python 3.9.6 on macOS arm64.
• Independently generated a matching signature with Ruby 2.6/OpenSSL using the upstream signing expression.
• Parsed the merged docs.json and checked navigation, introduction link, and retained GA4 configuration; git diff --check passed.
• Broken Link Check passed on head 46eaa9b: https://github.com/chatwoot/docs/actions/runs/39380608730. The earlier Mint installation failure no longer blocks this head.

Risks

No live Chatwoot instance or manual browser preview was used. The source/secret mapping is version-specific. Mintlify was not installed locally; the upstream workflow supplies the broken-link check evidence.

Follow-up

Maintainer review of the wording and version-specific secret retrieval guidance.

AI assistance: OpenAI Codex assisted with investigation, documentation, and validation.

[Sealdot]

Could a maintainer rerun the Broken Link Check when convenient? The first run stopped at npm i -g mint with ETARGET for @mintlify/cli@4.0.1520, before checking documentation. A subsequent registry lookup returned that version, but my attempt to rerun was denied because it requires repository admin rights.

The workflow is unchanged in this PR. The extracted Python example passed 19 local checks, including an independent Ruby OpenSSL signature vector. I am keeping the PR in draft pending the check and documentation preview.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-20T06:36:36.584100Z	46eaa9b	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.