Skip to main content

Overview

This guide provides step-by-step instructions to register, list, and secure webhooks using the webhook management API.

  • Register Webhook – Subscribe to one or more event types with a specified callback URL.
  • Retrieve Signing Secret – After registration, retrieve the HMAC signing secret to validate incoming notifications.
  • List Registered Webhooks – Retrieve all endpoints you have registered for your account.
  • All webhook callbacks include an HMAC signature for you to validate.

1. Prerequisites​

Before you begin:

  • You have access to the webhook management API.
  • You possess a valid JWT token for authentication.
  • You know your AccountId (UUID).
  • Your server has a public HTTPS endpoint to receive notifications.

2. Register a webhook​

Use the API to register a new webhook, specifying the event types you want to receive:

📘 View API Reference → Register Webhook

You must provide:

  • callbackUrl – your HTTPS endpoint to receive webhook callbacks.
  • eventTypes – a list of one or more event types to subscribe to (see Events for available types).

The event types you can subscribe to depend on your account type:

Account typeAllowed events
Account ownerCollection events (v1.collection.*) — payment requests, payments, payouts
PartnerOnboarding events (v1.onboarding.*) — account lifecycle, document review

Attempting to register events outside your account type will return a 400 Bad Request error.

3. Retrieve the signing secret​

After registering a webhook, call the signing secret endpoint to obtain the HMAC key for verifying incoming notifications:

📘 View API Reference → Get Webhook Signing Secret

  • Store the returned key securely — it is used to validate the HMAC signature on every webhook notification you receive.
  • The signing secret is generated by Hubpay and is unique per webhook registration.

4. List Registered Webhooks​

Use the API to list registered webhooks for review or management:

📘 View API Reference → List Registered Webhooks

5. Verifying webhook signatures​

Every webhook notification includes a signature you must verify before trusting the payload. For detailed instructions, including code examples in Python, Node.js and Java, see the dedicated Verifying webhook signatures guide.

6. Notes​

  • Signing secrets should be stored securely and kept private.
  • Only HTTPS endpoints should be used for sensitive webhooks.
  • If a webhook callback's signature does not validate, ignore the request.
  • For deleting a webhook, refer to the relevant API endpoint with your registered id.

7. Troubleshooting​

  • 401/403 errors: Ensure your JWT is valid.
  • 400 errors: Verify body fields callbackUrl and eventTypes are supplied and conforming.
  • No webhooks listed: Ensure you have registered at least one webhook for your account.

8. Summary​