Stripe Integration Guide

This guide shows you how to forward Stripe webhooks through Charon Gate so that critical billing events — invoice.paid, payment_intent.succeeded, customer.subscription.deleted — are captured durably and delivered reliably to your application.

Prerequisites

• A Charon Gate account (sign up free)
• A Stripe account with a webhook endpoint to configure

1. Create a Charon Gate endpoint

1. Log in to the Charon Gate dashboard
2. Go to Endpoints → New endpoint
3. Select the Stripe template from the provider list
4. Set Destination URL to your application's webhook handler (e.g. https://your-app.com/webhooks/stripe)
5. Note the Ingest URL — this is what you'll give to Stripe (looks like https://charongate.com/ingest/ep_…)

The Stripe template automatically configures Stripe's HMAC-SHA256 signature verification using your signing secret.

2. Add a Stripe webhook

1. Go to the Stripe Dashboard → Webhooks
2. Click Add endpoint
3. Set the URL to your Charon Gate ingest URL
4. Select the events you want to forward (recommended: invoice.paid, invoice.payment_failed, payment_intent.succeeded, customer.subscription.deleted, checkout.session.completed)
5. Click Add endpoint

3. Copy the signing secret

After creating the Stripe endpoint:

1. Click the endpoint in the Stripe Dashboard
2. Under Signing secret, click Reveal
3. Copy the secret (starts with whsec_)

Back in Charon Gate:

1. Open your endpoint → Settings
2. Paste the signing secret under Ingest signing secret
3. Save

Charon Gate now verifies every Stripe-Signature header before forwarding. Events with invalid signatures are rejected with a 400 and logged — they never reach your application.

4. Test the connection

Use the Test delivery button in Charon Gate to send a synthetic event to your destination. Or trigger a real Stripe event using the Stripe test dashboard.

Charon Gate logs the full delivery pipeline for each event: received time, verification status, forward attempt, HTTP status from your destination, and any retry schedule.

What Charon Gate handles for you

Concern	How Charon Gate handles it
Signature verification	HMAC-SHA256 with Stripe's Stripe-Signature + timestamp window
Your server is down	Retries with exponential backoff (up to 12 attempts by default)
All retries exhausted	Event enters DLQ; Slack/email alert fires
Stripe retries the same event	Deduplication via Stripe-Signature event ID; no double delivery
Your handler is slow	Charon Gate acknowledges Stripe immediately; your processing is async

Recommended Stripe events to capture

invoice.paid
invoice.payment_failed
invoice.upcoming
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
payment_intent.succeeded
payment_intent.payment_failed
checkout.session.completed

Troubleshooting

Events showing signature_verification_failed in Charon Gate → Check that you've saved the correct whsec_… secret. The secret changes every time you regenerate it in Stripe.

Events arriving at Charon Gate but not being forwarded → Check your destination URL is correct and accessible from the internet. Use the Health probe button to test reachability.

Stripe test events not appearing → Make sure you're using a Stripe test mode endpoint key and your Charon Gate ingest URL is correct.