Skip to content

Provider guide

Stripe webhooks with Hooksmith

To forward Stripe webhooks, add your hook's /h/<id> URL as a Stripe webhook endpoint and store the endpoint's whsec_ signing secret as STRIPE_WEBHOOK_SECRET. Hooksmith verifies the Stripe-Signature header on every request, filters and reshapes the event, and delivers it to your own endpoint with retries.

How Stripe signs webhooks

Hooksmith checks the Stripe-Signature header against the raw request bytes, the same way Stripe's libraries do.

Header
Stripe-Signature, in the form t=<unix seconds>,v1=<hex>. More than one v1= entry is accepted.
Algorithm
HMAC-SHA256, hex encoded.
What is signed
The timestamp, a dot, then the raw request body: <t>.<body>.
Key
The whole whsec_… string, used as is.
Replay window
The timestamp must be within 5 minutes of the server clock. Change it with source.verification.tolerance.
  • A failed check answers 401 VERIFICATION_FAILED before anything is stored, so a forged request never becomes an event.
  • Stripe creates one signing secret per endpoint, and test mode and live mode endpoints have different secrets. Use one hook per Stripe endpoint.

Set it up

Hooksmith turns the provider preset into a hook you own. The provider creates the signing secret when you add the endpoint, so deploy first, add the URL in the provider dashboard, then store the secret it shows you. Secrets live in your workspace vault and never go in the YAML. Store STRIPE_WEBHOOK_SECRET, DESTINATION_URL.

  1. In the Stripe Dashboard, open Workbench, then Webhooks, and add a destination of type webhook endpoint.
  2. Paste the /h/<id> URL that hooksmith deploy printed.
  3. Select the event types you need and leave Use thin events off. The example below reads data.object, which only snapshot events carry.
  4. Reveal the endpoint's signing secret (it starts with whsec_) and store it with hooksmith secrets set STRIPE_WEBHOOK_SECRET.
terminal
hooksmith login
hooksmith new stripe-billing --preset stripe --yes
# paste the example hook into .hooksmith/hooks/stripe-billing.yaml
hooksmith secrets set DESTINATION_URL
hooksmith test stripe-billing --payload ./invoice.json
hooksmith deploy stripe-billing   # prints the /h/<id> URL
# add the URL in the provider dashboard, copy its signing secret, then:
hooksmith secrets set STRIPE_WEBHOOK_SECRET

hooksmith new writes the preset's starter hook. Replace its contents with the example below, or edit it by hand. The CLI's built-in test sample is generic, so pass your own payload with --payload; a matching one is in the next section. The command reference is in the docs.

Forward paid invoices and completed checkouts

This hook skips every Stripe event except invoice.paid and checkout.session.completed, and sends your endpoint a small flat body instead of the full event.

.hooksmith/hooks/stripe-billing.yaml
apiVersion: hooksmith/v1
kind: Hook
metadata:
  name: stripe-billing
  description: Paid invoices and completed checkouts to the billing service
spec:
  source:
    preset: stripe
  destinations:
    - name: billing-api
      url: ${DESTINATION_URL}
      method: POST
      timeout: 8s
      retries:
        max: 5
        backoff: exponential
        initialDelay: 1s
  transform:
    engine: handlebars
    fields:
      stripe_event_id: "{{{id}}}"
      type: "{{{type}}}"
      object_id: "{{{data.object.id}}}"
      customer: "{{{data.object.customer}}}"
      amount: "{{{default data.object.amount_paid data.object.amount_total}}}"
      currency: "{{{data.object.currency}}}"
  conditions:
    - if: type != "invoice.paid" && type != "checkout.session.completed"
      then:
        skip: true
  variables:
    - name: STRIPE_WEBHOOK_SECRET
      from: secret
    - name: DESTINATION_URL
      from: secret
invoice.json
{
  "id": "evt_1QxExample",
  "type": "invoice.paid",
  "data": {
    "object": { "id": "in_1QxExample", "customer": "cus_Example", "amount_paid": 2900, "currency": "usd" }
  }
}
  • DESTINATION_URL is a workspace secret, so the URL stays out of the YAML. Store it with hooksmith secrets set DESTINATION_URL.
  • Values use triple braces so quotes, ampersands, apostrophes and equals signs reach your endpoint as typed. With double braces, template output is HTML-escaped.
  • Amounts stay in Stripe's smallest currency unit, as strings, because template output is text.
  • Hooksmith does not dedupe Stripe events by default: none of its default dedupe headers is a Stripe header. The body above carries stripe_event_id so your endpoint can ignore repeats.

Stripe event types people filter on

Stripe lets you pick event types on the endpoint, and its docs recommend receiving only the ones you handle. Hooksmith conditions can filter further on the type field of the body.

invoice.paid
An invoice was paid. Common trigger for provisioning.
invoice.payment_failed
A payment attempt on an invoice failed.
checkout.session.completed
A Checkout Session finished.
customer.subscription.created
A subscription started.
customer.subscription.updated
Plan, status or billing details changed.
customer.subscription.deleted
A subscription ended.
payment_intent.succeeded
A payment went through.
payment_intent.payment_failed
A payment attempt failed.
charge.refunded
A charge was refunded.
charge.dispute.created
A customer opened a dispute.

Test against localhost

The Hooksmith desktop app for Mac can tunnel stored events to a server on your machine. In raw mode it replays the original body bytes and the stored provider headers. Proxy headers such as x-forwarded-host are never stored, so they are not replayed. The target must be localhost, 127.0.0.1, [::1] or a *.localhost name. Get it on the download page.

Stripe rejects timestamps older than about 5 minutes, so resend fresh events only.

Questions

How does Hooksmith verify the Stripe signature?

It reads the Stripe-Signature header, rebuilds the signed string from the timestamp and the raw body, computes HMAC-SHA256 with your whsec_ secret and compares it in constant time with every v1 value. The timestamp must also be within 5 minutes of now. If anything fails, the request gets a 401 and nothing is stored.

What happens when Stripe retries an event?

Stripe retries undelivered events for up to three days in live mode. Hooksmith answers 200 as soon as the event is verified and stored, so a slow or failing endpoint of yours does not trigger Stripe retries. Hooksmith then retries your endpoint itself on 5xx responses, 408, 425, 429 and network errors. Hooksmith does not dedupe Stripe events by default, so use the event id (evt_…) in your own endpoint to ignore repeats.

Why does a Stripe event fail with a signature error?

The usual causes are the wrong secret (each endpoint has its own, and test and live differ), a timestamp more than 5 minutes old, or an event resent long after it was created. Hooksmith compares against the exact bytes it received, so body parsing is not the issue here. Check hooksmith secrets list to confirm STRIPE_WEBHOOK_SECRET exists.

Can I test Stripe webhooks against localhost?

Yes, with the Hooksmith desktop app for Mac. Its tunnel replays each stored event to a localhost URL in raw mode: the original body bytes and the Stripe-Signature header, so your local verification code still passes. Resending an event older than about 5 minutes fails Stripe's timestamp check. The Stripe CLI is a separate tool and is not required.

Does Hooksmith work with Stripe thin events?

Yes. A thin event is signed the same way, so verification is unchanged, but its body holds only the event type (prefixed v1., such as v1.invoice.paid), the event id and a related_object with the object id, type and API URL. There is no data.object, and Hooksmith does not call the Stripe API to fetch it. The Stripe preset falls back to related_object.id and matches the v1. types. Hooks that need object fields, like the example above, need snapshot events.

Does my endpoint still receive the Stripe signature?

No. Hooksmith verifies the original request, then sends your endpoint its own request with the transformed body. Each delivery carries x-hooksmith-event-id, x-hooksmith-delivery-id and x-hooksmith-attempt headers. Your endpoint can authenticate Hooksmith with a header you set on the destination.

Other providers

All providers are listed on webhook providers. Hooks are metered by events processed: see pricing.