Gateways notify the platform of payment events by POSTing to /api/v1/webhooks/{gateway}, where gateway is a configured payment driver. Anything else is rejected before it reaches application code.
Verification
- Stripe requests are verified against STRIPE_WEBHOOK_SECRET.
- PayPal requests are verified against PAYPAL_WEBHOOK_ID.
- Timestamps outside PAYMENT_WEBHOOK_TOLERANCE_SECONDS are refused, which is what stops a captured request being replayed later.
- The endpoint is rate-limited independently of the rest of the API.
Processing
Verified events are recorded in the webhook log, then applied — typically marking an invoice paid and releasing the matching provisioning job. Handling is idempotent, so a gateway retrying an event it already sent does not double-credit a payment.
Retention
Webhook logs are pruned nightly at 04:30 to keep the table from growing without bound. Inspect a recent delivery there before asking the gateway to resend.
NoteThe webhook URL must be reachable from the internet and terminate at your API domain. A gateway that cannot deliver will retry for a while and then stop, leaving invoices unpaid that were in fact charged.