Stripe

Stripe is a built-in inbound webhook source that ships inside @hogsend/engine. Point a Stripe webhook endpoint at /v1/webhooks/stripe, set one environment variable, and your customer, subscription, and invoice events flow straight into the ingestion pipeline — ready to trigger journeys, update contacts, and evaluate exit conditions.

What it does

The Stripe preset maps the billing lifecycle to Hogsend's event vocabulary so your journeys react to revenue moments:

• A new customer enters Hogsend as a contact, so a welcome or onboarding journey can fire on contact.created.
• A subscription change emits subscription.created / subscription.updated / subscription.deleted, so plan-change and cancellation flows have a trigger.
• An invoice event emits invoice.<action> (e.g. invoice.payment_failed, invoice.paid), so a dunning / churn-recovery journey can run when a charge fails.

Every transformed event runs through the same ingestion pipeline as PostHog and the REST API — store, route to journeys, exit-check, contact upsert.

Setup

1. Create the Stripe webhook endpoint

In the Stripe Dashboard, go to Developers → Webhooks → Add endpoint and set the URL to your Hogsend API:

https://api.hogsend.com/v1/webhooks/stripe

Select the events you want to forward (see Event mapping below). At minimum, subscribe to customer.created so later subscription/invoice events can resolve to a known contact.

2. Set the signing secret

Copy the endpoint's Signing secret (the whsec_… value Stripe shows for that endpoint) and set it in your Hogsend environment:

STRIPE_WEBHOOK_SECRET=whsec_...

That's it — no Stripe SDK, no extra dependencies. Hogsend verifies the stripe-signature header itself using node:crypto:

• It parses the t=<timestamp>,v1=<hex> header, recomputes the HMAC-SHA256 over <timestamp>.<raw body>, and constant-time compares against the v1 signature.
• The signed timestamp must be within a 5-minute tolerance of now.
• During secret rotation, multiple candidate secrets are accepted, so an in-progress rollover doesn't drop events.

The route reads the raw request body once and passes those exact bytes to both signature verification and the transform — so the signature checks the same payload Hogsend parses.

Event mapping

The preset normalizes Stripe event names into Hogsend's outbound vocabulary. Anything outside these prefixes is ignored (the transform returns null and the event is skipped):

<action> is passed through verbatim — customer.subscription.deleted becomes subscription.deleted, invoice.payment_failed becomes invoice.payment_failed.

Identity

Hogsend keys every Stripe event to the Stripe customer id:

• For customer events, the userId is the customer object's own id (e.g. cus_…).
• For subscription and invoice events, the userId is data.object.customer — the customer the subscription/invoice belongs to.

The userEmail is taken from data.object.email when present. The Stripe event id (payload.id) becomes the idempotencyKey, so Stripe's at-least-once redelivery dedupes on user_events.idempotencyKey rather than re-firing your journeys.

Property split

The preset follows Hogsend's contactProperties vs eventProperties split. Only customer.created / customer.updated carry a durable profile to merge — deletes and subscription/invoice events are event-only (their contactProperties is empty).

eventProperties (every Stripe event — lands on the user_events row, what a journey trigger.where / exitOn sees):

contactProperties (only on customer.created / customer.updated — merged onto the durable contact record):

Customer metadata is spread first, so the explicit name / phone / stripeCustomerId keys win if your metadata happens to use those names.

Enablement

A preset mounts only when both conditions hold: its secret env var is set and ENABLED_WEBHOOK_PRESETS allows it.

So with STRIPE_WEBHOOK_SECRET set and ENABLED_WEBHOOK_PRESETS unset, /v1/webhooks/stripe is live automatically. If STRIPE_WEBHOOK_SECRET is missing, the preset is never mounted regardless of the allow-list.

Override the preset

The preset registers under the id stripe. If you author your own defineWebhookSource({ meta: { id: "stripe" } }) in your app's src/webhook-sources/ and pass it to createApp, your source wins — the built-in preset is replaced for that id. Use this only when you need transform behavior the preset doesn't cover; for most apps, setting STRIPE_WEBHOOK_SECRET is the whole integration.

Using Stripe events in a journey

Once events are flowing, trigger a journey on any mapped event name. For example, a dunning flow on a failed payment:

import { defineJourney, days } from "@hogsend/engine";

export const dunning = defineJourney({
  meta: {
    id: "dunning",
    trigger: { event: "invoice.payment_failed" },
    // leave the journey if a later invoice succeeds for this customer
    exitOn: [{ event: "invoice.paid" }],
  },
  async run(user, ctx) {
    // ...send a "your payment failed" email, wait, escalate
  },
});

The eventProperties above (stripeCustomerId, _stripeEvent, stripeObject, …) are exactly what a trigger.where or exitOn.where evaluates — see Events & Ingestion and Conditions for the matching rules.