> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webhooktrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Capture Stripe webhooks, then prove your handler against duplicates, reordering, stale timestamps, retries and forged bodies.

## Point Stripe at your capture URL

**1. Copy your capture URL**

It is on **Arrivals** and in the header of every project page: `https://in.webhooktrap.dev/c/` followed by a 12-character key.

**2. Add a webhook destination in Stripe**

In test mode, open **Developers › Webhooks › Add destination**. Paste the URL, pick the events you handle, and save.

**3. Trigger events**

Trigger a test checkout, or any action that sends the events you picked. Stripe sends straight to the capture URL; no CLI is needed.

Webhook Trap recognises a Stripe delivery by its `Stripe-Signature` header, reads the event type and id from the body (`type`, `id`), and groups events by the object they are about: subscription, invoice, payment intent, checkout session and others.

![Arrivals with three Stripe deliveries in one subscription group and the selected delivery's detail.](https://mintcdn.com/jiordik/RqLSY6HivsmtT0rV/images/captures-stream.webp?fit=max\&auto=format\&n=RqLSY6HivsmtT0rV\&q=85\&s=8a1500a30b5dc77679e556b0db0c5278)

Stripe deliveries grouped by subscription.

## Configure the agent

```yaml webhooktrap.yml theme={"theme":{"light":"github-light","dark":"github-dark"}}
target: http://127.0.0.1:3000/webhooks/stripe
provider: stripe
secret: env:STRIPE_WEBHOOK_SECRET
probe:
  - as: orders.count
    cmd: psql "$DATABASE_URL" -Atc "select count(*) from orders"
reset: npm run db:reset:webhooks
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export STRIPE_WEBHOOK_SECRET=whsec_...
webhooktrap agent
```

If you leave out `secret`, the agent looks for `STRIPE_WEBHOOK_SECRET`, the name in the Stripe pack.

> [!NOTE]
>
> Your signing secret stays on your machine. `webhooktrap.yml` holds only the name of the environment variable (`secret: env:NAME`). The agent reads the value when it signs a delivery, strips every known secret variable from the environment of probe and reset commands, and refuses to write or upload a run document that contains the secret. The server learns the variable's name, never its value.

Stripe signs a timestamp with every delivery, and a captured signature goes stale after the 300-second tolerance. So without the secret the agent can't send a valid delivery: the run stops as **Couldn't start** with the reason `needs_secret`.

## What the scenarios do for Stripe

| Scenario | For Stripe |
| - | - |
| Once | Each selected event, re-signed now. |
| Twice | The first event again, 500 ms later, same body and event id, new `Stripe-Signature` timestamp. |
| Shuffled | The events in reverse order. Needs 2 or more events. |
| Late | The first event signed for a timestamp 360 s in the past (tolerance 300 s + 60 s). |
| Retry after error | The first event, then the same event 2 s after the first attempt completes. |
| Tampered | The body with one field changed, signed for the original body. The pack names the field per event type: `data.object.amount_paid` or `data.object.total` for `invoice.*`, `data.object.amount_received` or `data.object.amount` for `payment_intent.*`, `data.object.amount` for `charge.*`, `data.object.amount_total` for `checkout.session.*`. |
| Unsigned | The first event with `Stripe-Signature` removed. |
| Burst | Every selected event at once (two copies when you select one). |
| Slow budget | One more delivery, measured against the 10 s budget. |

The 10 s budget is the Webhook Trap default, not a limit taken from Stripe's docs, so you can lower or raise it with `budget:` in `webhooktrap.yml`.

## Common findings

* **Accepts tampered payload** (Critical): the handler returned 2xx, or changed state, for a body Stripe never signed. Verify with `stripe.webhooks.constructEvent` on the raw body and return 400 when it throws, before any write.
* **Duplicate delivery changed `<probe>` again** (High): Twice or Retry after error wrote twice. Record `event.id` before the write and return 200 when it is already recorded.
* **Accepts a stale signature** (High): Late was accepted. Use the SDK's timestamp tolerance.

See [Scenarios](https://docs.webhooktrap.dev/reference/scenarios.md) and [Findings and exit codes](https://docs.webhooktrap.dev/reference/findings.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.