Stripe Webhooks

Webhooks are how Stripe tells the platform what happened — a payment succeeded, a subscription changed, a dispute opened.

Where to find it

Architect Panel → Automation:

• Workflow Builder — rules that fire on a webhook event

Architect Panel → Activity:

• Error Log — rejected or malformed webhooks

Architect Panel → Configuration:

• Instance Configuration Fields — the API key and signing secret

The endpoint

Stripe posts to the platform’s subscription webhook endpoint, with the tenant identified in the request. That tenant determines which Stripe account’s key is used to verify and process the event — which is what allows several tenants to have separate Stripe accounts on one installation.

Every request is verified

Against the signing secret, using Stripe’s own verification. The platform is strict about this on purpose:

• No signing secret configured — the request is refused and an error written, rather than every webhook failing obscurely.
• No signature header — refused.
• Signature does not verify — refused.

This matters because the endpoint is public. Without verification, anybody could post a "payment succeeded" event.

Every event is logged

Each event is recorded with its type, its Stripe event identifier, the object it concerned and its timestamp. Event types are registered automatically the first time they are seen, so the list of types builds itself from real traffic rather than needing to be predicted.

Full payload logging exists but is off by default, because payloads contain customer data.

Reacting to events is automation, not code

The important point. Every verified event fires the platform’s rules — before and after processing — with the event type as the trigger.

So handling payment failed means writing a rule against that event, not editing a handler. Notifying somebody about a dispute, flagging an account when a subscription is cancelled, recording an invoice: all of these are rules.

Which events to react to

Start narrow. Failed payments and cancellations are the two most organisations need. Add others when there is a specific thing you want to happen, rather than building rules for events nobody acts on.

The log is your diagnostic

When something did not happen, the first question is whether the event arrived. The log answers that immediately, and separates "Stripe did not tell us" from "we were told and did nothing".

The gateway log is shared

Direct Debit events are recorded in the same place, distinguished by gateway. So a single view shows everything that arrived from any payment provider.

Worked example

A shop has two rules: a failed payment notifies the account owner and flags the subscriber record, and a cancellation writes a note against the customer. When a customer claimed they had never been told about a failed payment, the event log showed the event arriving and the rule firing that morning.

Recommendations

• Set the signing secret — nothing works without it.
• Handle events with rules, not custom code.
• Start with failures and cancellations.
• Check the event log first when something did not happen.
• Leave verbose payload logging off unless diagnosing.