Webhook Endpoints

Stripe Webhook

Endpoint: POST /stripe/webhook

Description: Receives events from Stripe when a credit purchase is completed.

Security:

Stripe signature verification using STRIPE_WEBHOOK_SECRET
Returns 400 Invalid signature if verification fails
Returns 400 Invalid payload if the payload is malformed

Events Handled:

Event	Description
`checkout.session.completed`	A credit purchase was successful. Credits are atomically added to the institute’s balance.

Metadata Expected:

Field	Type	Description
`institute_id`	integer	The institute to credit
`credits`	integer	Number of credits to add

Idempotency: The endpoint checks Transaction::where('stripe_session_id', $session->id) before processing. Duplicate webhooks return 200 Already processed without double-crediting.

Response Codes:

Code	Meaning
`200 OK`	Event processed or already processed
`400 Invalid signature`	Webhook signature verification failed
`400 Invalid payload`	Payload could not be parsed
`200 Missing metadata`	Required metadata fields were absent (logged as error)