Troubleshooting

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.

Secret-related errors

Set a provider-specific env var or generic fallback:

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