Skip to main content

Webhooks with HMAC Signatures

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

Overview​

  • 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.
  • No API Key or Bearer Token registration options are discussed (focus: HMAC only).

1. Prerequisites​

Before you begin:

  • You have access to the Webhook Registration API endpoint.
  • 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 (HMAC Protected)​

Use this endpoint to register your webhook:

HTTP Request​

POST /v1/webhooks/register

Headers​

  • Authorization: Bearer <YOUR_JWT_TOKEN>
  • AccountId: <YOUR_ACCOUNT_ID>
  • Content-Type: application/json

Request Body​

  • webhookUrl — The HTTPS URL of your webhook endpoint (required).
  • sharedKey — Your shared HMAC secret for securing payloads (required).

Example JSON:

{ "callbackUrl": "https://yourapp.example.com/webhook-endpoint", "sharedKey": "f7b3ca9275d949d9b74f7f1b..." }

Example Registration (cURL)​

bash curl -X POST [https://api.example.com/v1/webhooks/register](https://api.example.com/v1/webhooks/register)
-H "Authorization: Bearer <YOUR_JWT_TOKEN>"
-H "AccountId: <YOUR_ACCOUNT_ID>"
-H "Content-Type: application/json"
-d '{ "callbackUrl": "[https://yourapp.example.com/webhook-endpoint](https://yourapp.example.com/webhook-endpoint)", "sharedKey": "f7b3ca9275d949d9b74f7f1b..." }'

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

Successful Response​

  • HTTP status: 200 OK
  • No body content: registration is successful if no error is returned.

3. List Registered Webhooks​

List your registered webhooks for review or management.

HTTP Request​

GET /v1/webhooks/list?page=0&size=20

Headers​

  • Authorization: Bearer <YOUR_JWT_TOKEN>
  • AccountId: <YOUR_ACCOUNT_ID>

Example (cURL)​

bash curl -X GET "[https://api.example.com/v1/webhooks/list?page=0&size=20](https://api.example.com/v1/webhooks/list?page=0&size=20)"
-H "Authorization: Bearer <YOUR_JWT_TOKEN>"
-H "AccountId: <YOUR_ACCOUNT_ID>"

Example Response​

The API returns a paginated list of registered webhooks:

{ "content": [
  {  
   "id": "cfd86c98-d7e9-4465-8aa0-e0614ccdeeed", 
  "endpointUrl": "https://yourapp.example.com/webhook-endpoint", 
  "hmacHeaderName": "x-hub-signature", 
  "algorithm": "SHA_256", 
  "status": "ACTIVE" } 
  ] , 
  "totalPages": 1, 
  "totalElements": 1, 
  "size": 20, 
  "number": 0
}

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.
  • API keys and Bearer tokens are not required or discussed here.
  • 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​

  • Register using /v1/webhooks/register with callbackUrl and sharedKey.
  • List using /v1/webhooks/list.
  • Validate all incoming payloads with your HMAC sharedKey and the SHA_256 algorithm.