Error code: webhook_signature_invalid

What triggers it

A webhook signature failed verification. A wrong signing secret, a re-serialised body, or a timestamp outside the 300-second tolerance.

Example response

{
  "error": {
    "type": "invalid_request_error",
    "code": "webhook_signature_invalid",
    "message": "A webhook signature failed verification."
  }
}

How to fix it

Verify over the raw body with the correct secret; check for clock skew.

This is deterministic; fix the cause before resending. See the error code catalogue for related codes.

In practice

In a well-built client, webhook_signature_invalid is handled by branching on error.code rather than on the human error.message, which may be reworded over time. The HTTP status (400) gives the broad invalid_request_error class; the code gives the specifics; and, on field errors, error.param pinpoints the input to fix.

This code is deterministic — retrying the identical request reproduces it — so keep it out of your retry path and instead map it to a clear, actionable message. See Map errors to user-facing messages and Read the error envelope for the pattern.