Skip to main content

Stripe Webhook Setup

Allegro fulfills purchases — creating entitlements and recording the transaction — when it receives a checkout.session.completed event from Stripe. Without a webhook configured, fulfillment only happens when the member is redirected back to your site after checkout. Configuring the webhook makes fulfillment reliable regardless of what the member does after paying.

Environment Variables​

Before setting up the webhook endpoint, make sure the following environment variables are set in your Allegro instance:

VariableDescription
STRIPE_CONNECT_CLIENT_IDThe client ID of your Stripe Connect application (from the Stripe Dashboard → Connect settings).
STRIPE_SECRET_KEYYour Stripe platform secret key (sk_live_... or sk_test_...).
STRIPE_PUBLISHABLE_KEYYour Stripe publishable key (pk_live_... or pk_test_...).
STRIPE_WEBHOOK_SECRETThe signing secret for the webhook endpoint (see below). Set this after creating the endpoint.

Webhook URL​

Allegro exposes a single webhook endpoint for all payment providers:

POST /api/webhooks/stripe

The full URL for your instance is:

https://your-allegro-instance.com/api/webhooks/stripe

Replace your-allegro-instance.com with your actual domain.

Creating the Webhook Endpoint​

  1. Log in to the Stripe Dashboard.
  2. Go to Developers → Webhooks.
  3. Click Add endpoint.
  4. Set Endpoint URL to https://your-allegro-instance.com/api/webhooks/stripe.
  5. Under Listen to, choose Events on Connected accounts.
  6. Click Select events, then find and check checkout.session.completed.
  7. Click Add events, then click Add endpoint.
Use Connected Account events

Allegro uses Stripe Connect. The webhook must be set to listen for events on Connected accounts, not just your platform account. If you configure it for your platform account only, checkout completions from connected Stripe accounts will not trigger the webhook.

Setting the Signing Secret​

After creating the endpoint, Stripe displays a Signing secret (starts with whsec_).

  1. Copy the signing secret.
  2. Set it as the STRIPE_WEBHOOK_SECRET environment variable in your Allegro deployment.
  3. Restart the application to pick up the new value.

Allegro uses this secret to verify that incoming webhook requests are genuinely from Stripe. Requests with an invalid or missing signature are silently ignored.

How It Works​

When Stripe sends a checkout.session.completed event to your endpoint:

  1. Allegro verifies the Stripe-Signature header against STRIPE_WEBHOOK_SECRET.
  2. Allegro resolves the tenant from the session metadata.
  3. Allegro fulfills the checkout: creates the purchase record, grants entitlements to the audience member, and records any associated events.
  4. Allegro returns 200 OK.

The controller always returns 200 regardless of outcome — this prevents Stripe from retrying on transient application errors that should not be retried.

note

If a checkout.session.completed event arrives before the member has been redirected back (which can happen if the redirect is slow), Allegro handles it gracefully. The token exchange on the return page detects the already-fulfilled purchase and skips duplicate fulfillment.

Testing with the Stripe CLI​

During local development you can forward webhook events from Stripe to your local instance using the Stripe CLI:

stripe listen --forward-to http://localhost:8000/api/webhooks/stripe

The CLI prints a temporary webhook signing secret on startup. Set this as STRIPE_WEBHOOK_SECRET in your local .env while testing:

STRIPE_WEBHOOK_SECRET=whsec_...

Trigger a test event to verify the endpoint is working:

stripe trigger checkout.session.completed

Check your application logs for the fulfillment result.