HookSteadBETA

Guide / Integrations

Stripe → HookStead → your app

Record, verify and forward every Stripe event with retries and replay.

Put Hookstead between Stripe and your backend: every Stripe event is recorded, verified, and forwarded with retries, and you can replay any of them later.

1. Create a source in Hookstead

Sources → New source:

  • Verify requests with: None for now. Stripe only gives you its signing secret once it knows the URL, so you switch verification on in step 2.
  • Dedupe: Stripe event ids are unique, so dedupe on them and a redelivered event isn't stored twice. Stripe sends no id header, so set this through the API: PATCH /api/v1/workspaces/{wsId}/sources/{id} with {"dedupeStrategy": {"jsonPath": "$.id"}}.

Copy the source's ingest URL: https://<your Hookstead>/in/<token>.

2. Point Stripe at Hookstead

In the Stripe dashboard: Developers → Webhooks → Add endpoint, with the ingest URL as the endpoint URL, and select the events you need. Then copy the endpoint's signing secret (whsec_…) and, on the source's page, set Verify requests with: Stripe with that secret. Changing verification needs the admin role. Do this before sending real traffic.

To try it locally with the Stripe CLI:

bash
stripe listen --forward-to "https://<your Hookstead>/in/<token>"   # prints a whsec_… for the source
stripe trigger payment_intent.succeeded

Hookstead checks Stripe-Signature (HMAC-SHA256 over the timestamp and raw body, 5-minute tolerance). Unsigned or tampered requests get 401 and aren't stored.

3. Forward to your app

Destinations → New destination with your endpoint's URL, then connect the Stripe source to it. Store the destination's signing secret: your app verifies Hookstead's webhook-signature with it (see the receivers).

Verify Hookstead's signature, not Stripe's. Hookstead forwards Stripe-Signature unchanged, but Stripe signs a timestamp that is only valid for 5 minutes, so a retry or replay later than that fails Stripe's check. Hookstead's signature is fresh on every attempt.

4. Operate

  • Failed deliveries retry with backoff. Set an alert (Alerts → New rule, e.g. "failures in a row") so you hear about an outage at your end.
  • After fixing a bug, replay the events it mishandled from the event page, or bulk-retry failed deliveries.
  • Your app should still treat Stripe events as at-least-once: dedupe on the event's id (or on Hookstead's webhook-id).