# Webhook stripe verify

`webhook-stripe-verify` · version 1.0.0 · Hashing & signatures · free, no key needed

Verify a Stripe webhook's Stripe-Signature header against a raw payload, with secret-rotation and tolerance support.

**Use when you need to: verify stripe webhook signature · check stripe-signature header · validate an incoming stripe event.**

## Decide before calling

Read the [versioned contract](/v1/tools/webhook-stripe-verify/versions/1.0.0) and the supported scope below. Reuse `webhook-stripe-verify@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `webhook-stripe-verify@1.0.0` for verify stripe webhook signature. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- verify stripe webhook signature
- check stripe-signature header
- validate an incoming stripe event
- is this webhook really from stripe
- stripe signing secret manual verification
- verify a rotated stripe secret against multiple v1 signatures

## Not supported

- computing a fresh Stripe-Signature header for a test delivery (see webhook-signature-compute)
- verifying any other vendor webhook scheme (see webhook-slack-verify, webhook-standard-verify, webhook-twilio-verify)

## Behavior

- signature_header is split on commas into 'key=value' pairs. The FIRST 't=' pair's value is parsed as a decimal integer -> timestamp (a header with no 't=' pair, or whose value is not a valid decimal integer, is reason 'header_unparsable', timestamp null, matched_scheme null). Every 'v1=' pair's value is collected, in order, as candidate signatures; a header with a valid timestamp but zero v1= pairs is reason 'no_v1_signature' (matched_scheme null; a 'v0=' or other scheme is simply not collected, not an error by itself).
- The signed string is the CANONICAL decimal string of the parsed timestamp integer (e.g. a header with 't=007' parses to the same signed string as 't=7') followed by a literal '.' followed by payload verbatim (raw text, never re-serialized).
- expected = lowercase-hex(HMAC-SHA256(secret as UTF-8 bytes verbatim -- including its 'whsec_' prefix, never stripped -- signed string as UTF-8 bytes)). The tool constant-time-compares expected against EVERY collected v1 candidate; any one match is sufficient (secret rotation). No match is reason 'signature_mismatch', matched_scheme still 'v1'.
- Tolerance is ONE-SIDED: when now is given and tolerance_seconds > 0, the check is (now - timestamp) > tolerance_seconds -- a timestamp in the FUTURE never fails this check, no matter how far in the future. This is checked only after a signature match succeeds. tolerance_seconds 0 or now omitted -> timestamp_checked false, no freshness check at all.
- matched_scheme is 'v1' whenever header parsing got far enough to attempt a signature comparison (reason signature_mismatch, timestamp_outside_tolerance, or valid true); it is null only for header_unparsable or no_v1_signature.
- secret is never echoed in the output or in any error details.

## Input

- `payload` (string, required): max length 262144
- `signature_header` (string, required): min length 1; max length 4096
- `secret` (string, required): min length 1; max length 512
- `now` (integer, optional): min 0; max 99999999999
- `tolerance_seconds` (integer, optional): min 0; max 86400; default 300

## Output

- `valid` (boolean, required)
- `reason` (one of "header_unparsable", "no_v1_signature", "signature_mismatch", "timestamp_outside_tolerance", null, required)
- `timestamp` (integer or null, required)
- `timestamp_checked` (boolean, required)
- `matched_scheme` (one of "v1", null, required)

## Limits

- max payload bytes: 262144

## Example

Request input:

```json
{
  "payload": "{\"id\":\"evt_1\"}",
  "signature_header": "t=1614000000,v1=e6bce1af69d4a58ca43b91bd6c94e6cccc1c8a1cbf68d6dc6a2e1fbdc4536dd2",
  "secret": "whsec_test_secret"
}
```

Response:

```json
{
  "result": {
    "valid": false,
    "reason": "signature_mismatch",
    "timestamp": 1614000000,
    "timestamp_checked": false,
    "matched_scheme": "v1"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "webhook-stripe-verify",
  "version": "1.0.0",
  "input": {
    "payload": "{\"id\":\"evt_1\"}",
    "signature_header": "t=1614000000,v1=e6bce1af69d4a58ca43b91bd6c94e6cccc1c8a1cbf68d6dc6a2e1fbdc4536dd2",
    "secret": "whsec_test_secret"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/webhook-stripe-verify/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"payload":"{\"id\":\"evt_1\"}","signature_header":"t=1614000000,v1=e6bce1af69d4a58ca43b91bd6c94e6cccc1c8a1cbf68d6dc6a2e1fbdc4536dd2","secret":"whsec_test_secret"}'
```

The machine-readable contract is at [/v1/tools/webhook-stripe-verify/versions/1.0.0](/v1/tools/webhook-stripe-verify/versions/1.0.0).

### CLI

```sh
node cli.mjs run webhook-stripe-verify 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Webhook slack verify](/tools/webhook-slack-verify): Verify a Slack request's X-Slack-Signature against its raw body and timestamp, with an absolute replay-window check.
- [Webhook twilio verify](/tools/webhook-twilio-verify): Verify a Twilio X-Twilio-Signature against a URL and form params or a JSON body, trying Twilio's port-variant URLs.
- [Merkle proof verify](/tools/merkle-proof-verify): Recompute a Merkle root (RFC 9162 or Bitcoin) from one leaf and its audit path, and compare it to a claimed root.
- [Webhook standard verify](/tools/webhook-standard-verify): Verify a Standard Webhooks (Svix/Clerk/Resend) webhook-signature header against its id.timestamp.payload signing string.
- [Hmac verify](/tools/hmac-verify): Recompute an HMAC and compare it, constant-time, to a signature that may carry a literal prefix and be truncated.
- [Checksum manifest verify](/tools/checksum-manifest-verify): Parse a GNU/BSD checksum manifest (sha256sum -c, tagged form) and verify caller-supplied file contents against it.