Skip to content

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

  1. 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.

    terminal
    curl -fsSL https://hooksmith.tech/install.sh | bash
    hooksmith login
  2. 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.

    terminal
    hooksmith init
    hooksmith new stripe-local --preset stripe --yes
    .hooksmith/hooks/stripe-local.yaml
    apiVersion: 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: secret
    
  3. Step 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.

    terminal
    hooksmith secrets set DESTINATION_URL
  4. Step 4: Deploy the hook and copy its URL

    deploy prints only the ingest URL on stdout. Copy it.

    terminal
    hooksmith deploy stripe-local
    # https://hooksmith.tech/h/<id>
  5. 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.

    terminal
    printf %s "$WHSEC" | hooksmith secrets set STRIPE_WEBHOOK_SECRET
  6. 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 URL
    http://localhost:3000/webhooks/stripe
  7. 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.
terminal
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.