Guide
How to test Stripe webhooks on localhost
Create a Hooksmith hook with the Stripe preset, point a Stripe endpoint at the hook's https://hooksmith.tech/h/<id> URL, then start the Tunnel in Hooksmith for Mac. Each new Stripe event is replayed to your local URL, for example http://localhost:3000/webhooks/stripe, with the original body bytes and the Stripe-Signature header, so your own signature check passes. Hooksmith is the public endpoint. Your laptop makes outbound requests only, so nothing needs to reach it from the internet.
Before you start
- A Mac on macOS 13 Ventura or later, with Hooksmith for Mac installed.
- A Hooksmith account.
- The Hooksmith CLI. The first step installs it; it needs bun, which the installer sets up if it is missing.
- A Stripe account in test mode and a local app that accepts POST requests and verifies Stripe signatures.
- One public HTTPS URL that answers with a 2xx status. A hook must have at least one destination, and destinations cannot be localhost. The tunnel does not use it in raw mode, but Hooksmith still delivers there.
Steps
Step 1: Install the CLI and sign in
hooksmith login prints a short code and opens hooksmith.tech/device. Approve it there. The token is stored in ~/.hooksmith/credentials.json.
terminalcurl -fsSL https://hooksmith.tech/install.sh | bash hooksmith login
Step 2: Create a hook from the Stripe preset
--preset stripe skips the agent and writes the starter hook. The preset sets Stripe signature verification with a 5 minute tolerance, so you only name the provider.
The transform and conditions in the starter hook shape a notification. In raw tunnel mode your app gets the original Stripe request instead, so you can leave them as they are.
terminalhooksmith init hooksmith new stripe-local --preset stripe --yes
.hooksmith/hooks/stripe-local.yamlapiVersion: hooksmith/v1 kind: Hook metadata: name: stripe-local description: Stripe → destination spec: source: preset: stripe destinations: - name: primary url: ${DESTINATION_URL} method: POST timeout: 8s retries: max: 3 backoff: exponential initialDelay: 500ms transform: engine: handlebars fields: title: Stripe · {{type}} message: "{{default data.object.description (default data.object.id related_object.id)}}" interruption_level: active conditions: - if: type == "payment_intent.payment_failed" || type == "invoice.payment_failed" || type == "charge.failed" || type == "v1.payment_intent.payment_failed" || type == "v1.invoice.payment_failed" || type == "v1.charge.failed" then: transform: fields: title: Stripe payment failed message: "{{default data.object.last_payment_error.message (default data.object.failure_message related_object.id)}}" interruption_level: time-sensitive - if: type == "charge.dispute.created" || type == "v1.charge.dispute.created" then: transform: fields: title: Stripe dispute opened interruption_level: critical variables: - name: STRIPE_WEBHOOK_SECRET from: secret - name: DESTINATION_URL from: secretStep 3: Store the destination URL
The hook reads its destination from the DESTINATION_URL secret. Set it to any public HTTPS URL that answers with a 2xx status. Hooksmith delivers the transformed event there too, and a destination that fails is retried and can trigger a failure email.
Secrets are encrypted at rest and write-only. The command reads the value from a hidden prompt, so it stays out of your shell history.
terminalhooksmith secrets set DESTINATION_URL
Step 4: Deploy the hook and copy its URL
deploy prints only the ingest URL on stdout. Copy it.
terminalhooksmith deploy stripe-local # https://hooksmith.tech/h/<id>
Step 5: Add the endpoint in Stripe and store its signing secret
In the Stripe Dashboard, open Workbench, then Webhooks, and add a destination of type webhook endpoint. Paste the ingest URL and choose the events you want. Leave Use thin events off: your app then receives the full event, exactly as Stripe sent it. Reveal the destination's signing secret (it starts with whsec_).
Store it as STRIPE_WEBHOOK_SECRET. Hooksmith uses it to verify each request, and your local app needs the same value to verify the replayed copy. Do not use the secret printed by stripe listen; that one belongs to a different endpoint.
terminalprintf %s "$WHSEC" | hooksmith secrets set STRIPE_WEBHOOK_SECRET
Step 6: Start the tunnel in Hooksmith for Mac
Install the app from the download page, open it, and choose Sign in. The app uses the same code approval as the CLI.
Open Tunnel, pick stripe-local, and enter your local URL. Leave the mode on Raw, which replays the stored request with the exact body bytes and the provider's headers. Choose Start Tunnel.
The app polls Hooksmith every few seconds for new events of that hook and posts each one to your URL, in order. Events that arrived before you pressed Start Tunnel are not replayed.
local URLhttp://localhost:3000/webhooks/stripe
Step 7: Trigger a Stripe event and watch the log
In test mode, do something that fires one of the events you selected. The Event Log in the Tunnel view shows each forward with its status, HTTP status, latency and your app's response body. Select a row to see the details and to use Resend Event.
How to check it works
Check three places.
- In Hooksmith for Mac, the new row in the Event Log has the status forwarded and the HTTP status your app returned.
- Your app received a POST with a stripe-signature header, plus x-hooksmith-tunnel: 1 and x-hooksmith-event-id. Hooksmith adds those two so you can tell a tunneled request from a direct one.
- hooksmith logs stripe-local lists the event. Its status is delivered once the destination answered with a 2xx.
hooksmith logs stripe-local
Troubleshooting
Nothing is listening on http://localhost:3000/webhooks/stripe. Start your local app, then Resend.
Your app is not running on that host and port. Start it, then select the row and choose Resend.
No response from the local URL within 10 seconds.
The tunnel waits 10 seconds for your app to answer. Return a response before doing slow work.
The local app answered HTTP 400.
Hooksmith delivered the request and your app refused it. A common cause is a signature check that uses the wrong secret or a re-serialized body. Verify against the raw body with the signing secret of the Stripe endpoint that points at Hooksmith.
The local app answered HTTP 301, a redirect that Hooksmith does not follow.
Use the final URL, for example the one with the trailing slash your framework redirects to.
The local target must be http or https on localhost, 127.0.0.1, [::1] or *.localhost, without credentials.
The tunnel only forwards to your own machine. Use one of those hosts and leave out any user name or password.
This hook does not keep payloads (logging.retainPayload: false), so Hooksmith cannot replay its events.
The tunnel replays stored requests. Remove logging.retainPayload: false from the hook, deploy it again, and start the tunnel.
Providers like Stripe reject signatures older than ~5 minutes; your local verification may fail on resend.
Resend fresh events only. Trigger a new event in Stripe instead of resending an old row.
Sign in to keep the tunnel running.
The app lost its session. Open Account in the app, sign in again, and restart the tunnel.
Stripe reports failed attempts with Stripe: signature mismatch or Stripe: timestamp outside tolerance (HTTP 401), or Secret not found: STRIPE_WEBHOOK_SECRET (HTTP 400).
Hooksmith rejected the request before it was stored. Store the endpoint's own signing secret with hooksmith secrets set STRIPE_WEBHOOK_SECRET. Check that the machine clock is right if the timestamp is outside the 5 minute tolerance.
Related
- Stripe webhooks with HooksmithWhat the Stripe preset verifies and which secrets it needs.
- Hooksmith for MacDownload the app and read what the tunnel can and cannot do.
- Retry, replay and debug failed deliveriesWhen the destination, not your laptop, is the problem.
- DocsCLI reference, secrets and the desktop app.