Hubpay webhooks

Webhooks notify your backend when a Hubpay resource changes. Use them to update payment, onboarding, RFI and app-connection state without repeatedly polling the API.

Treat each webhook as a prompt to fetch current state. Delivery can be retried or arrive out of order, so handlers must be idempotent.

Prerequisites

• A bearer token
• A public HTTPS callback endpoint
• The event types required by your integration

Register a webhook

Call Register webhook with:

• callbackUrl: the HTTPS endpoint that receives callbacks
• eventTypes: one or more event selectors: exact event names from the event catalogue, wildcards such as v1.collection.*, or a mix (see Subscribing with wildcards)
• AccountId header (optional): app connection partners wishing to receive customer activity event callbacks to different urls on a per-connection basis set this to the customerAccountId returned on the active connection. If not set, partners will receive callbacks for all registered events to the specified URL - customer activity event payloads will include the customer account id for disambiguation.

The event families available to you depend on your Hubpay account and integration permissions: account owners can receive collection (v1.collection.*) and RFI (v1.rfi.*) events; partners can also receive onboarding (v1.onboarding.*) and connection (v1.connection.*) events. Registering an exact event name outside what your account can receive returns 400 Bad Request.

Subscribing with wildcards

Event names are hierarchical (v1.<family>.<object>.<action>), and you can subscribe at any level of that hierarchy by ending a selector with .*. A wildcard matches every event beneath the prefix, at any depth:

Selector	Subscribes to
v1.*	Every event your account can receive
v1.collection.*	All collection events: payment requests, payments and payouts
v1.collection.payment_request.*	Payment-request lifecycle events and the payment and payout events beneath them
v1.collection.payment_request.payment.*	Payment events and the payout events beneath them
v1.rfi.*	RFI case and RFI document events
v1.collection.payment_request.paid	Exactly one event

{
  "callbackUrl": "https://your-callback.url/webhook",
  "eventTypes": ["v1.collection.payment_request.*", "v1.rfi.case.opened"]
}

Wildcards are forward compatible: when Hubpay adds a new event type under a prefix you have subscribed to, your endpoint starts receiving it automatically, with no change to your registration. Subscriptions made with exact event names only ever receive those events. Whichever you use, every delivered message names its concrete event type in the event field, so route on that in your handler.

Wildcards expand to the events your account can receive, so v1.* is valid for every account type and simply resolves to a different set. A selector that matches nothing, a bare *, or a wildcard in the middle of a name (v1.*.created) returns 400 Bad Request.

List webhooks returns both eventTypes (the selectors you registered) and resolvedEventTypes (the concrete event types they currently expand to), which is the quickest way to check what an endpoint will receive.

Retrieve the signing secret

After registration, call Get webhook signing secret. Store the returned key in a secret manager.

Every callback includes an HMAC signature. Verify it against the raw request body before parsing or processing the payload. See Verifying webhook signatures for Python, Node.js and Java examples.

Handler requirements

• Return a 2xx response promptly after accepting a valid event
• Process longer-running work asynchronously
• Deduplicate events using the event identifier
• Fetch the latest resource state before taking irreversible action
• Monitor failures and understand the retry schedule

Manage registrations

• List webhooks
• Register webhook
• Get signing secret

See the webhook event catalogue for event names and payload fields.