Webhooks
Webhooks let you receive real-time notifications about payment events directly to your backend systems, enabling automated order fulfillment, reconciliation, customer comms, and more.
Hubpay uses webhooks to notify you about key events for all payment flows—including Hosted Payment Pages and Payment Links.
How webhooks work
When a significant event occurs (such as a payment being completed or cancelled), Hubpay sends an HTTP POST request with a JSON payload to a webhook endpoint you specify.
You can set up your endpoint to receive notifications for one or more event types.
Setting up webhooks
-
Register your endpoint
Configure your webhook endpoint via the API. -
Receive events
Listen for incoming POST requests at your endpoint. Each request includes the event type along with associated items. -
Acknowledge delivery
Respond with HTTP 2xx to confirm receipt. Hubpay retries delivery if your server doesn’t respond.
Common payment webhook events
| Event Type | Description |
|---|---|
v1.collection.payment_request.created | The payment request is first generated |
v1.collection.payment_request.part_paid | A partial payment is captured but the payable balance > 0 |
v1.collection.payment_request.paid | The request balance reaches 0 |
v1.collection.payment_request.cancelled | The request is unpaid and is cancelled |
For the full list of events and sample payloads, see Webhooks.
Security best practices
- Verify signatures: Hubpay may include a signature or secret for webhook verification—always validate requests.
- HTTPS only: Always use HTTPS for your webhook endpoint.
- Idempotency: Webhooks can be retried—make your endpoint idempotent.
Delivery & retries
- Hubpay retries failed webhook deliveries using exponential backoff.
- Respond with HTTP 2xx as soon as you successfully process the event.
- Log and monitor webhook events for operational visibility.