Agent skill

Stripe Webhooks Skill

Receive and verify Stripe webhooks. Use when setting up Stripe webhook handlers, debugging signature verification, or handling payment events like payment_intent.succeeded, customer.subscription.created, or invoice.paid.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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:

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:

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:

Common Event Types

EventDescription
payment_intent.succeededPayment completed successfully
payment_intent.payment_failedPayment failed
customer.subscription.createdNew subscription started
customer.subscription.deletedSubscription canceled
invoice.paidInvoice payment successful
checkout.session.completedCheckout session finished

For full event reference, see Stripe Webhook Events

Environment Variables

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

Local Development

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

Reference Materials