Skip to main content

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 types from the event catalogue
  • 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.

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​

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