Webhooks
StudentPay delivers signed HTTPS webhooks for checkout lifecycle events when WEBHOOK_SECRET and WEBHOOK_DESTINATION_URL are configured.
Implemented events
| Event | When |
|---|---|
checkout.created |
New provider checkout created |
checkout.confirmed |
Enrolment confirmed |
direct_debit.authorised |
Pinch/DDA capture completed |
direct_debit.failed |
DDA capture failed |
agreement.generated |
Agreement PDF stored |
Planned later
| Event | When |
|---|---|
payment_plan.activated |
Plan moved into active collection |
payment.failed |
Instalment failed |
payment.confirmed |
Instalment collected |
plan.in_arrears |
Plan entered arrears |
plan.cancelled |
Plan cancelled |
Signature & retries
Header: X-StudentPay-Signature: t=<unix>,v1=<hex>
Canonical string: ${timestamp}.${rawBody} signed with HMAC-SHA256 using WEBHOOK_SECRET.
Delivery retries up to 3 attempts in-request (0 / 250 / 750 ms backoff) with the same event_id. See also X-StudentPay-Delivery-Attempt.
Full guide: API repo docs/webhooks.md.