Events

Webhook Events Guide

Audience: partners integrating with our push notification service.

Scope: all webhook events across payment requests, payments, onboarding, and more

Version: 1.0

---

1. Overview

Hubpay emits webhook events to inform your system about real-time changes to resources such as payment requests, payments and onboarding.

You can subscribe to events by registering a webhook endpoint. Once subscribed, we’ll send signed HTTPS POST requests to your server with the relevant event data so your system can react in real‑time (update UI, trigger fulfilment, etc.).

---

2. Event catalogue

Event	When it triggers
v1.onboarding.account.created	On successful creation of new account.
v1.onboarding.account.signed_up	On acceptance of account sign-up details.
v1.onboarding.account.rejected	On rejection of account sign-up details or documentation.
v1.onboarding.account.submitted	On submission of account sign-up details (incl. documentation) for review and decision.
v1.onboarding.account.approved	On approval of account sign-up details (incl. documentation).
v1.onboarding.account.onboarded	The account is fully onboarded and able to transact.
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
v1.collection.payment_request.payment.created	Reserved for future use. Intended to represent an initial state
v1.collection.payment_request.payment.pending	Authorised (for card payments), pending confirmation (for crypto), or reported as sent by the customer
v1.collection.payment_request.payment.received	Funds received on blockchain, card network, or bank
v1.collection.payment_request.payment.completed	Final payout made; funds credited to wallet
v1.collection.payment_request.payment.failed	Payment failed due to error or rejection
v1.collection.payment_request.payment.reversed	Reserved for future use. Intended to represent a post-completion reversal

For details on each event type and its typical flow, see the dedicated documentation for that sub-category:

• Account onboarding
• Payment request
• Payments

---

3. Event format

Hubpay uses thin events — minimal, lightweight webhook messages designed for stability, safety, and forward compatibility.

What are thin events?

Thin events are compact and granularly scoped. Instead of sending large payloads each event includes:

• Stable identifiers (e.g. paymentRequestId) and resource type
• A minimal data object (often optional)
• No embedded resource bodies

Each webhook is an HTTPS POST with a small, JSON payload:

{
  "id": "<event-uuid>",
  "event": "v1.collection.payment_request.created",
  "createdAt": "2025-06-25T13:04:11Z",
  "accountId": "<your-account-uuid>",
  "relatedObject": {
    "id": "<resource-uuid>",
    "type": "collection.payment_request",
    "url": "v1/collections/payment-requests/<id>"
  },
  "data": {
    // Optional — varies by event
  }
}

We sign every message with an hmac-signature header and exponentially retry. See our webhooks overview and callbacks API documentation for more details.

---

4. Receiving events

To start receiving and handling webhooks:

1. Register your webhook URL
   Call POST /v1/webhooks with your callback URL and secret key.

2. Listen for signed webhook events
   We will send HTTPS POST requests to your registered endpoint for every relevant event. See our detailed callbacks API for the expected payload/request.

3. Verify the signature
   See webhook verification guide

4. Process the event

   • Inspect the event field (e.g. v1.collection.payment_request.created)
   • Take appropriate action in your system (e.g. update UI, trigger fulfilment, notify user)
   • See the event catalogue for supported values

5. Return HTTP 200 OK
   A 200 response acknowledges successful receipt. Any other response (e.g. 500, 400, timeout) triggers automatic retries with exponential backoff.

---