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 and, where required, an AccountId
  • 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

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.