Sosyabot Docs

Appearance

Stripe Webhook ​

Stripe is the default billing provider when BILLING_PROVIDER=stripe. Without a webhook, Sosyabot doesn't see successful payments or subscription changes — your users will pay but the workspace won't unlock.

Endpoint ​

`<BASE_URL>/api/v1/webhooks/billing/stripe`

The signing secret must match the value in your .env:

STRIPE_WEBHOOK_SECRET=whsec_...

Events to subscribe to ​

In the Stripe dashboard, register the endpoint and select these event types:

  • payment_intent.succeeded
  • payment_intent.payment_failed
  • subscription_schedule.created
  • subscription_schedule.updated
  • subscription_schedule.canceled
  • invoice.paid
  • invoice.payment_failed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted

Local development ​

Use the Stripe CLI:

bash
stripe listen --forward-to localhost:4200/api/v1/webhooks/billing/stripe

The CLI prints a temporary whsec_... — paste it into your local .env and restart the API.

Verification ​

Sosyabot verifies every inbound webhook by computing the HMAC-SHA256 signature against the raw body using STRIPE_WEBHOOK_SECRET. Verification failures return 400 invalid signature and the event is dropped — Stripe will retry per its standard backoff schedule.

Don't reuse the secret across environments

Each Stripe environment (test mode, live mode, CLI listener) has a distinct signing secret. Rotating environments without rotating STRIPE_WEBHOOK_SECRET will silently 400 every event.

Stripe billing

ENV Reference

OAuth Callback URLs