Troubleshooting

CLI is running, but no webhooks are captured

Checklist:

• Confirm your provider points to the correct URL (http://localhost:3001/webhooks/your-provider).
• If your provider cannot reach localhost, expose the capture server through a tunnel (for example ngrok or cloudflared).
• Verify the capture server is actually running:

better-webhook capture --port 3001

captures replay says capture not found or selector is ambiguous

• List captures first and copy a concrete capture ID:

better-webhook captures list

• Use the full or unique prefix capture ID:

better-webhook captures replay <capture-id> http://localhost:3000/api/webhooks/github

Signature verification fails in SDK handlers

Most failures come from one of these:

• Wrong secret value (<PROVIDER>_WEBHOOK_SECRET, such as GITHUB_WEBHOOK_SECRET, or fallback WEBHOOK_SECRET).
• Body parser mutated the request body before verification.
• Provider is signing with a different secret than your environment.

For framework-specific raw-body requirements, see Adapters.

NestJS or Express handlers behave unexpectedly

• Express must use express.raw({ type: "application/json" }) for webhook routes.
• NestJS should preserve raw body and handle 204 responses with .end() when no response body is returned.

Reference examples: SDK Getting Started and Adapters.

templates run fails with secret-related errors

If a template requires provider signing placeholders, pass a secret explicitly:

better-webhook templates run github-push http://localhost:3000/api/webhooks/github --secret "$GITHUB_WEBHOOK_SECRET"

Or set a provider-specific env var (or generic fallback):

• <PROVIDER>_WEBHOOK_SECRET (for example GITHUB_WEBHOOK_SECRET)
• WEBHOOK_SECRET

better-webhook command is not found after installation

• Verify installation:

better-webhook --version

• If installed manually, make sure the binary is on your PATH.
• If using Homebrew, retry install:

brew install --cask endalk200/tap/better-webhook