Stripe Webhook Setup

Getting Stripe webhooks flowing through Watchtower takes about five minutes. The trickiest part is keeping test and live signing secrets separate, so this guide walks through both.

Before you start

You'll need:

• A Webhook Watchtower account with a workspace
• Access to your Stripe dashboard (developer permissions or higher)

Step 1: Create a source in Watchtower

1. Go to Sources in your project.
2. Click Add source and choose Stripe as the provider.
3. Give it a name ("Stripe" is pre-filled, but "Stripe live" or "Stripe test" works better if you're setting up both environments).
4. Leave the signing secret blank for now; you'll come back to fill it in after the next step.
5. Click Create source and copy the ingest URL.

Create one source for Stripe test mode and a separate one for live mode. They use different signing secrets and should stay separate in your event log.

Step 2: Add the endpoint in Stripe

1. In the Stripe dashboard, go to Developers → Webhooks.
2. Click Add endpoint.
3. Paste your Watchtower ingest URL into the Endpoint URL field.
4. Under Events to send, select the event types you want to receive, or choose All events if you're not sure yet.
5. Click Add endpoint.

Stripe creates the endpoint immediately. You'll be taken to the endpoint detail page.

Step 3: Copy your signing secret

On the endpoint detail page, find the Signing secret section and click Reveal. Copy the value (it starts with whsec_).

Go back to your Watchtower source settings, paste the signing secret, and save.

Test vs live: Stripe has separate webhook endpoints for test mode and live mode. Make sure you're in the right mode (top-left toggle in the Stripe dashboard) when creating each endpoint, and that the signing secret you copy matches the Watchtower source it's going into.

Step 4: Send a test event

Back in Stripe, open your new endpoint and click Send test webhook. Choose an event type and send it.

The event should appear in your Watchtower dashboard within a few seconds with a Verified stamp. If you see Failed, the signing secret doesn't match. Re-copy it from Stripe and update your source.

Duplicate event detection

Watchtower automatically detects when Stripe sends the same event more than once. Stripe assigns a unique ID to every event (starting with evt_) and includes it in the request body. Watchtower stores this ID and compares it against events already received for the same source.

If a duplicate arrives:

• It's stored with a Duplicate label and a link to the original event
• It's not forwarded to your destinations
• It doesn't count toward your monthly event usage

This handles the common case where Stripe retries after a timeout. Because Watchtower returns 200 to Stripe when an event arrives, retries should be rare. If they do happen, your downstream services won't see the same event twice.

What Stripe's signature looks like

Stripe puts the signature in the Stripe-Signature header as a comma-separated list:

t=1714000000,v1=abc123...,v0=def456...

The t value is the Unix timestamp of the request. The v1 value is the HMAC-SHA256 signature. Watchtower constructs the signed payload as {timestamp}.{body} before verifying. This matches Stripe's spec exactly.

Common issues

Failed verification despite correct secret: double-check you're using the right mode. A test-mode signing secret won't verify live-mode events.

Events not appearing at all: go to Stripe → Developers → Webhooks → your endpoint → Recent deliveries. If Stripe shows a delivery attempt with a non-2xx response, the ingest URL may be wrong. If there are no delivery attempts, check that the event type you're testing is included in your endpoint configuration.

400 from Stripe: Stripe sometimes sends 400 if the endpoint URL returns an error before Stripe logs a delivery. Confirm the ingest URL is exactly as shown in your source settings with no trailing slash or extra characters.