Configure webhooks

Goal

Ensure Stripe events reach Beacon with cryptographic validation, idempotency, and safe replay.

Recommended procedure

1. 11) Define a stable endpoint

   Use a dedicated public HTTPS endpoint for webhooks without redirects.

2. 22) Store the signing secret

   Keep the secret in your secrets manager, never in source code.

3. 33) Implement idempotency

   Process by event.id and skip already acknowledged duplicates.

4. 44) Configure safe replay

   Keep a replay window and an audit trail per event.

Signature verification sample

curl -X POST https://api.beacon.pt/v1/webhooks/stripe \
-H "Content-Type: application/json" \
-H "Stripe-Signature: t=1710492000,v1=fake-signature" \
-d '{"id":"evt_123","type":"invoice.paid"}'

Definition of done

• Error rate under 1% per rolling 15-minute window.
• Event reprocessing available by event.id.
• Logs correlate event, organization, and fiscal pipeline.