Debug Stripe webhooks with signature verification

Stripe signs every webhook delivery with an HMAC-SHA256 signature in the Stripe-Signature header. Before you wire Stripe to your real backend, use the Webhook Debugger to confirm that your signing secret is correct, inspect the full payload structure, and replay individual events without waiting for Stripe to resend them.

What you’ll accomplish

Configure the actor to verify Stripe-Signature automatically
Point your Stripe dashboard webhook URL at the generated endpoint
Inspect captured events and confirm signatureValid: true
Replay a specific event to staging after fixing downstream code
Set up alerts for signature failures

Configure the actor for Stripe

Start the actor with the following input. Replace whsec_replace_me with your actual Stripe webhook signing secret from the Stripe dashboard.

{
  "urlCount": 1,
  "retentionHours": 72,
  "authKey": "stripe-debug-key",
  "enableJSONParsing": true,
  "maskSensitiveData": true,
  "redactBodyPaths": [
    "body.data.object.customer_email",
    "body.data.object.metadata.internal_note"
  ],
  "signatureVerificationSecret": "whsec_replace_me",
  "signatureVerification": {
    "provider": "stripe",
    "tolerance": 300
  },
  "defaultResponseCode": 200,
  "defaultResponseBody": "{\"received\":true}",
  "forwardUrl": "https://staging.example.com/webhooks/stripe",
  "forwardHeaders": true,
  "replayMaxRetries": 3,
  "replayTimeoutMs": 10000,
  "alerts": {
    "slack": {
      "webhookUrl": "https://hooks.slack.com/services/AAA/BBB/CCC"
    }
  },
  "alertOn": ["signature_invalid", "5xx"]
}

Set forwardHeaders: true if your downstream receiver also validates Stripe-Signature. The actor preserves the original header when forwarding.

After the actor starts, call /info to retrieve the generated webhook URL and confirm the active webhook ID.

Point Stripe at your generated endpoint

Open the Stripe dashboard

Go to Developers → Webhooks in the Stripe dashboard and click Add endpoint.

Paste the generated URL

Copy the /webhook/:id URL from /info and paste it into the Endpoint URL field.

Select events

Choose the event types you want to test, such as payment_intent.succeeded or checkout.session.completed.

Copy the signing secret

After saving the endpoint, click Reveal under Signing secret and copy the whsec_... value into your actor input.

Stripe frequently updates their webhook IP ranges. If you set allowedIps, check the Stripe IP documentation to keep your list current. Signature verification alone is more stable than IP allowlisting.

Inspect a captured event

After Stripe delivers an event, query /logs to see what was captured:

curl "https://<run-id>.runs.apify.net/logs?webhookId=wh_abc123&limit=10"

A captured Stripe event looks like this:

{
  "id": "evt_8m2L5p9xR",
  "webhookId": "wh_abc123",
  "timestamp": "2026-01-30T12:00:00.000Z",
  "method": "POST",
  "statusCode": 200,
  "contentType": "application/json",
  "signatureValid": true,
  "signatureProvider": "stripe",
  "body": {
    "type": "payment_intent.succeeded",
    "data": {
      "object": {
        "amount": 9999,
        "currency": "usd"
      }
    }
  }
}

signatureValid: true confirms the actor verified the Stripe-Signature header against your signing secret. To filter for a specific event type after JSON parsing is enabled:

GET /logs?webhookId=wh_abc123&body.type=checkout.session.completed

To retrieve the full payload for an event that was offloaded due to size:

GET /logs/evt_8m2L5p9xR/payload

Replay a Stripe event after fixing a bug

Once you fix the downstream handler, replay the original captured event to staging without waiting for Stripe to resend it:

curl -X POST \
  "https://<run-id>.runs.apify.net/replay/wh_abc123/evt_8m2L5p9xR?url=https%3A%2F%2Fstaging.example.com%2Fwebhooks%2Fstripe"

The replay endpoint sends the original method and payload, automatically hydrates any large body that was offloaded to storage, and strips masked or transport-managed headers before forwarding.

Use ?__status=500 appended to the webhook URL to force a temporary failure path and observe Stripe retry behavior without changing your saved actor configuration.

Set up alerts for signature failures

Add an alerts block to your actor input and set alertOn to include signature_invalid:

{
  "alerts": {
    "slack": {
      "webhookUrl": "https://hooks.slack.com/services/AAA/BBB/CCC"
    }
  },
  "alertOn": ["signature_invalid", "5xx"]
}

The actor posts a notification to the configured Slack channel whenever a delivery fails signature verification. You can query the same failures directly:

GET /logs?webhookId=wh_abc123&signatureValid=false

Common failure patterns

Signal	What it usually means	What to do
`signatureValid=false`	Wrong signing secret, modified raw body, or stale timestamp tolerance	Verify the `whsec_...` secret and inspect the raw captured request before any downstream transformation
5xx sender response	Your test profile is simulating a failure, or a custom script changed `event.statusCode`	Remove the forced status or replay a healthy event after the fix is deployed
Forwarding failures	The webhook was accepted but the downstream bridge failed later	Check the `alertOn` notifications for `error` or `5xx` events, or review `/system/metrics` for forwarding error counts

Get Started

Core Features

Security

Configuration

Guides

Help

Debug Stripe webhooks with signature verification

What you’ll accomplish

Configure the actor for Stripe

Point Stripe at your generated endpoint

Inspect a captured event

Replay a Stripe event after fixing a bug

Set up alerts for signature failures

Common failure patterns

​What you’ll accomplish

​Configure the actor for Stripe

​Point Stripe at your generated endpoint

​Inspect a captured event

​Replay a Stripe event after fixing a bug

​Set up alerts for signature failures

​Common failure patterns

What you’ll accomplish

Configure the actor for Stripe

Point Stripe at your generated endpoint

Inspect a captured event

Replay a Stripe event after fixing a bug

Set up alerts for signature failures

Common failure patterns