Webhooks API

Goal

Ingest Stripe events with signature verification, event-level deduplication, and controlled replay for incident recovery.

Primary endpoints

Processing model

1. 11) Receive event

   Validate signature and minimum payload shape.

2. 22) Deduplicate

   Use provider event.id as the logical deduplication key; duplicates return duplicate: true.

3. 33) Persist and process

   Store internal webhookEventId and run async handlers safely.

4. 44) Confirm state

   Update business state and delivery metrics; billing can upsert subscriptions.

Canonical URLs by environment

• test: https://test.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=test
• live: https://app.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=live
• If you use the dedicated billing endpoint, keep the same convention on /api/webhooks/stripe/billing.

Retry and replay policy

• Automatic retries must preserve original event context.
• Manual replay uses the internal webhookEventId, not Stripe event.id.
• Avoid broad replay operations without impact prioritization and explicit validation criteria.

General endpoint response example

{
  "ok": true,
  "webhookEventId": "whevt_123",
  "eventId": "evt_123",
  "mode": "test",
  "duplicate": false
}

Manual replay example

curl -X POST "https://test.beacon.pt/api/billing/webhooks/whevt_123/replay?org=acme&mode=test" \
  -H "Authorization: Bearer <beacon_session_token>"

Operational signals