Webhooks

Point Stripe at ParityRail so a customer is re-checked the moment their subscription changes.

Webhooks let ParityRail re-check a customer the instant their Stripe subscription changes, instead of waiting for the next scheduled scan. They’re optional but recommended — without them, the daily scan still catches everything, just once a day instead of instantly.

Before you start

Stripe already connected on step 2 — you add the signing secret to that same integration.
Access to the Stripe Dashboard → Developers → Webhooks to add an endpoint.
Your project’s webhook URL — shown at the bottom of the Stripe onboarding step, in the “Webhook endpoint” block, with a copy button.
Admin role on the ParityRail project to save the signing secret.

Connect the endpoint

In ParityRail onboarding step 2 (Stripe), scroll to the “Webhook endpoint” block at the bottom and click its copy button — the URL already has your project id filled in:
```
https://<your-host>/api/webhooks/stripe/{projectId}
```
In the Stripe Dashboard, go to Developers → Webhooks → Add endpoint and paste the URL.
Select the events to send. Stripe’s dashboard recommends customer.subscription.*, invoice.payment_failed, and checkout.session.completed. Sending every event is fine too — the extras are just logged. The full set ParityRail acts on:
```
checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_failed
entitlements.active_entitlement_summary.updated
```
Save the endpoint, open it, and copy its Signing secret (starts with whsec_).
Back in ParityRail onboarding step 2, click “Reconnect”if you’re already connected, paste the secret into the “Webhook signing secret (optional)” field, and click “Test & connect”.
Trigger a subscription change — or use Stripe’s “Send test event” — to confirm ParityRail re-checks the customer.

Verify it worked

There’s no in-UI “webhook verified” indicator — connecting a signing secret is stored, not tested. Saving marks the integration as webhook-configured as soon as a whsec_… secret is present; the secret itself is only exercised when Stripe actually delivers an event.

The “Stripe connected” card persists after you reconnect — that confirms the secret saved.
The real confirmation: send a real or test event from the Stripe endpoint. A 200in Stripe’s webhook logs, plus a fresh fulfillment check for that customer appearing in ParityRail’s run history or incident inbox, means it worked end to end.

Troubleshooting

Symptom	Fix
Stripe shows 400 on deliveries	The signing secret is missing or wrong — requests with a missing or invalid signature are rejected with 400 and never processed. Recopy the endpoint's whsec_ secret and re-save it on step 2 via Reconnect.
Events arrive (200) but no re-check happens	You subscribed only to event types outside the handled set. Add the seven events listed above, or send all events.
Demo project	Live webhook traffic is ignored entirely by design — a demo-mode Stripe integration never processes real events.
Duplicate deliveries	Harmless. Each event is keyed by (projectId, eventId), so processing is idempotent — a duplicate is acknowledged 200 with no extra work.
An event never finishes processing	ParityRail responds 500 so Stripe redelivers it, and files a webhook_lag access incident if it stays stuck.

Without webhooks, ParityRail’s daily full scan still catches every incident — just once a day instead of instantly. See Scheduled checks for the schedule and its CRON_SECRET requirement.

You can also trigger a check yourself at any time — see the API reference.