# Stripe Webhooks

## When to Use This Skill

* Setting up Stripe webhook handlers
* Debugging signature verification failures
* Understanding Stripe event types and payloads
* Handling payment, subscription, or invoice events

## Verification (core)

Stripe ships official SDK helpers that verify the `Stripe-Signature` header (HMAC-SHA256 over `timestamp.body`) and parse the event in one call. Pass the raw request body — don't `JSON.parse` first.

Node:

```javascript
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const event = stripe.webhooks.constructEvent(
  rawBody,                                  // Buffer or string of the raw HTTP body
  req.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET         // whsec_… from the webhook endpoint settings
);
// Throws Stripe.errors.SignatureVerificationError on tampering or stale timestamp

```

Python:

```python
import stripe

event = stripe.Webhook.construct_event(
    raw_body,                                 # bytes of the raw HTTP body
    request.headers["stripe-signature"],
    os.environ["STRIPE_WEBHOOK_SECRET"],
)
# Raises stripe.error.SignatureVerificationError on tampering or stale timestamp

```

> For complete handlers with route wiring, event dispatch, and tests, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks/examples/fastapi/)

## Common Event Types

| Event | Description |
| --- | --- |
| `payment_intent.succeeded` | Payment completed successfully |
| `payment_intent.payment_failed` | Payment failed |
| `customer.subscription.created` | New subscription started |
| `customer.subscription.deleted` | Subscription canceled |
| `invoice.paid` | Invoice payment successful |
| `checkout.session.completed` | Checkout session finished |

> For full event reference, see [Stripe Webhook Events](https://docs.stripe.com/api/events/types)

## Environment Variables

```bash
STRIPE_SECRET_KEY=sk_test_xxxxx      # From Stripe dashboard
STRIPE_WEBHOOK_SECRET=whsec_xxxxx    # From webhook endpoint settings

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 stripe --path /webhooks/stripe

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/stripe-webhooks/references/overview.md) - Stripe webhook concepts
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/stripe-webhooks/references/setup.md) - Dashboard configuration
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/stripe-webhooks/references/verification.md) - Signature verification details