Stripe Webhook Trigger stripe-webhook

When to Use

• Post-payment fulfillment: Provision product access, generate a licence key, or send a purchase confirmation email immediately after a charge.succeeded event, without polling the Stripe API.
• Subscription lifecycle management: React to payment_intent.succeeded and payment_intent.payment_failed events to activate, suspend, or downgrade customer subscriptions in your system.
• Failed payment retry workflows: On a failed charge event, trigger a dunning sequence — send a payment-failure email, schedule a retry after 48 hours, and alert account managers for high-value customers.
• Invoice reconciliation: Use charge.succeeded events to auto-reconcile open invoices in your ERP, matching the Stripe customer ID and amount to internal records.
• Refund notifications: When a charge.refunded event arrives, trigger a customer notification workflow and update inventory or licence revocation if applicable.

Configuration

Security

Event Filtering

Sample Configuration JSON

{
  "webhookSecret": "{{ $credentials.stripe-webhook-secret }}",
  "allowedEventTypes": "charge.succeeded,charge.refunded,payment_intent.payment_failed",
  "minimumAmount": 100,
  "allowedCurrencies": "USD,EUR",
  "enableIdempotencyCheck": true,
  "requireKnownCustomer": true
}

Validation Errors

Output

Success Port

Error Port

Fires when signature verification fails, the timestamp window is exceeded, the event type is filtered out, or the request body cannot be parsed as valid JSON. The output contains errorCode and message fields. All verification failures are logged for security audit trail purposes.

Sample Output JSON — charge.succeeded

{
  "event_id": "evt_1QaB2cD3eF4gH5iJ6kL7mN8",
  "event_type": "charge.succeeded",
  "payment_intent": "ch_3QaB2cRKJHMJBpXx1Y2Z3A4B",
  "amount": 4999,
  "currency": "USD",
  "customer_id": "cus_QaB2cD3eF4gH5iJ",
  "status": "succeeded",
  "description": "Subscription — Pro Plan — May 2026",
  "metadata": {
    "order_id": "ORD-2026-05-1234",
    "plan": "pro"
  },
  "timestamp": "2026-05-26T08:30:00Z",
  "_webhook_method": "POST",
  "_webhook_path": "/webhooks/payment/success",
  "_webhook_received_at": "2026-05-26T08:30:00.812Z"
}

Expression Reference

Node Policies & GuardRails

• Never skip signature verification. The node uses constant-time HMAC-SHA256 comparison of the raw request body using the signing secret. Do not configure a blank secret. Verification failure routes to the error port and is logged — it does not silently pass through.
• Store the signing secret in Credentials Manager. The webhook signing secret grants the ability to spoof Stripe events. Reference it as {{ $credentials.stripe-webhook-secret }}. Rotate it immediately if it is ever exposed.
• Use event_id as an idempotency key for order fulfillment. Stripe retries failed webhook deliveries for up to 72 hours. Set enableIdempotencyCheck: true and use {{ $output.stripe.event_id }} as the idempotency key in any downstream node that provisions access, charges a customer, or writes a fulfillment record.
• Store raw events for replay capability. Before processing the event, write the raw Stripe event body to a durable store (database or S3). If your fulfillment workflow fails after processing has started, you can replay the event from the stored body without relying on Stripe's retry window.
• Set amount thresholds for high-value alert workflows. Use minimumAmount to route large payments (e.g. over $1,000) to a separate workflow that includes fraud review or account manager notification steps.
• Test with Stripe CLI before production. Use stripe trigger charge.succeeded via the Stripe CLI to send a signed test event to your development BizFirstAI endpoint. Validate that the signature is accepted, the output fields are populated as expected, and the downstream workflow completes correctly before enabling the endpoint in production.
• Monitor server clock synchronisation. The 5-minute timestamp window requires the BizFirstAI server to have accurate system time. Configure NTP synchronisation on all server instances. A clock drift of more than 5 minutes will cause all Stripe webhook events to be rejected as potential replay attacks.

Examples

Post-Payment Fulfillment — Provision Subscription Access

{
  "webhookSecret": "{{ $credentials.stripe-webhook-secret }}",
  "allowedEventTypes": "charge.succeeded",
  "allowedCurrencies": "USD,EUR,GBP",
  "minimumAmount": 1,
  "enableIdempotencyCheck": true,
  "requireKnownCustomer": true
}

Fires only for successful charges linked to a known Stripe customer. The downstream workflow uses {{ $output.stripe.customer_id }} to look up the internal account record, activates the subscribed plan, and sends a purchase confirmation email. The idempotency check prevents double-provisioning if Stripe retries the event.

Failed Payment Dunning — Retry and Notify

{
  "webhookSecret": "{{ $credentials.stripe-webhook-secret }}",
  "allowedEventTypes": "charge.failed,payment_intent.payment_failed",
  "enableIdempotencyCheck": true,
  "requireKnownCustomer": true
}

Triggers a dunning workflow whenever a charge fails. The workflow sends a payment failure email to the customer using {{ $output.stripe.customer_id }} and {{ $output.stripe.amount }} to personalise the message, then schedules an automatic retry after 48 hours using a Delay node. If a second attempt fails, an account manager notification is dispatched.

High-Value Payment Alert — Fraud Review Routing

{
  "webhookSecret": "{{ $credentials.stripe-webhook-secret }}",
  "allowedEventTypes": "charge.succeeded",
  "minimumAmount": 100000,
  "allowedCurrencies": "USD",
  "enableIdempotencyCheck": true,
  "includeFullEventObject": false
}

Only processes charges of $1,000 USD or more. Each qualifying payment routes to a fraud-review workflow that posts the payment details — {{ $output.stripe.amount }}, {{ $output.stripe.customer_id }}, and {{ $output.stripe.metadata }} — to an internal Slack channel and creates a review task in Jira. Normal payments below the threshold are handled by a separate workflow with a lower minimumAmount setting.