Stripe Integration

Set up HookWatch to receive Stripe webhooks for payment events like successful charges, subscription updates, and refunds.

Prerequisites

Step 1: Create a HookWatch endpoint

  1. Go to your Endpoints page
  2. Click "Create Endpoint"
  3. Enter a name like "Stripe Webhooks"
  4. Enter your destination URL (where you want webhooks forwarded)
  5. Copy the generated webhook URL

Your HookWatch URL will look like:

https://hook.hookwatch.dev/wh/abc123xyz

Step 2: Configure Stripe webhooks

  1. Go to Stripe Dashboard > Developers > Webhooks
  2. Click "Add endpoint"
  3. Paste your HookWatch URL in the "Endpoint URL" field
  4. Select the events you want to receive (see recommended events below)
  5. Click "Add endpoint"

Recommended events for most use cases:

checkout.session.completed
payment_intent.succeeded
payment_intent.payment_failed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_failed

Step 3: Save your webhook secret

After creating the endpoint in Stripe, you'll see a Signing secret (starts with whsec_). Save this securely - you'll need it to verify webhook signatures.

Important

HookWatch forwards the original Stripe-Signature header, so you can still verify webhook authenticity on your server.

Step 4: Verify webhooks on your server

Use Stripe's SDK to verify the webhook signature on your server. Here's an example:

Node.js / Express

Testing the integration

Stripe provides a way to send test webhooks:

  1. Go to your webhook endpoint in Stripe Dashboard
  2. Click "Send test webhook"
  3. Select an event type and click "Send test webhook"
  4. Check your HookWatch Events page to see the event

You can also use the Stripe CLI to forward test webhooks locally during development.

Common issues

Webhook signature verification fails

Make sure you're using the webhook secret from the specific endpoint you created, not your Stripe API secret key. Each webhook endpoint has its own unique signing secret.

Webhooks not arriving

Check that your endpoint is set to receive events in the correct mode (test vs. live). Stripe test mode and live mode have separate webhook configurations.

400 Bad Request on your server

Ensure you're parsing the raw request body, not JSON. Stripe's signature verification requires the raw body exactly as received.