# 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[​](#environment-variables "Direct link to Environment Variables")

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

| Variable                   | Description                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `STRIPE_CONNECT_CLIENT_ID` | The client ID of your Stripe Connect application (from the Stripe Dashboard → Connect settings). |
| `STRIPE_SECRET_KEY`        | Your Stripe platform secret key (`sk_live_...` or `sk_test_...`).                                |
| `STRIPE_PUBLISHABLE_KEY`   | Your Stripe publishable key (`pk_live_...` or `pk_test_...`).                                    |
| `STRIPE_WEBHOOK_SECRET`    | The signing secret for the webhook endpoint (see below). Set this after creating the endpoint.   |

## Webhook URL[​](#webhook-url "Direct link to Webhook URL")

Allegro exposes a single webhook endpoint for all payment providers:

```text
POST /api/webhooks/stripe

```

The full URL for your instance is:

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

```

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

## Creating the Webhook Endpoint[​](#creating-the-webhook-endpoint "Direct link to Creating the Webhook Endpoint")

1. Log in to the [Stripe Dashboard](https://dashboard.stripe.com).
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[​](#setting-the-signing-secret "Direct link to 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[​](#how-it-works "Direct link to 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[​](#testing-with-the-stripe-cli "Direct link to Testing with the Stripe CLI")

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

```bash
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:

```text
STRIPE_WEBHOOK_SECRET=whsec_...

```

Trigger a test event to verify the endpoint is working:

```bash
stripe trigger checkout.session.completed

```

Check your application logs for the fulfillment result.

## Related[​](#related "Direct link to Related")

* [One-off Purchases](/developer/guides/payment/purchases.md) — Initiating checkout from the SDK
* [Payment Provider (Product)](/product/entitlements/payment-provider.md) — Connecting a payment provider as an operator