Skip to main content

Overview

This guide provides step-by-step instructions to register and list webhooks using the webhook management API, focusing exclusively on registration that uses HMAC signatures for securing webhook notifications.

  • Register a Webhook – Securely receive event notifications by specifying your endpoint and a shared HMAC key.
  • List Registered Webhooks – Retrieve all endpoints you have registered for your account.
  • All callbacks will 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:

📘 View API Reference → Register Webhook

  • The sharedKey is used by the event provider to compute HMAC signatures for each webhook notification.
  • The HMAC algorithm is SHA_256.

3. List Registered Webhooks​

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

📘 View API Reference → List Registered Webhooks

4. Validating Incoming HMAC Signatures​

For each webhook POST notification you receive, the provider will include an HMAC signature (typically in a header such as X-Hubpay-Hmac). You should:

  1. Extract the payload and the provided signature header.
  2. Recompute the HMAC using your shared key and the payload, with the SHA_256 algorithm.
  3. Compare (use constant-time comparison) your result with the signature from the header.
  4. Only trust messages where the signatures match.

5. Notes​

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

6. Troubleshooting​

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

7. Summary​