Skip to main content

Tutorial: Testing Hubpay Webhooks — Including Postman

This tutorial will walk you through testing Hubpay webhook integrations, from registering your webhook endpoint to receiving and verifying webhook events. Testing can be done easily using Postman for API interaction and a simple webhook receiver service.

1. Set Up a Webhook Receiver​

To test webhooks, you need a publicly reachable endpoint.

Option 1: Use Webhook.site​

  1. Visit https://webhook.site.
  2. It gives you a unique URL (e.g., https://webhook.site/your-unique-id).
  3. You'll see all POSTs sent to this URL instantly.

Option 2: Run a Local Webhook Listener with ngrok​

  1. Start a basic HTTP server on your machine (e.g., using Node.js, Python, etc.).
  2. Expose it using ngrok: 
    ngrok http 8080
  3. Note the HTTPS URL (e.g., https://random.ngrok.io).

2. Register Your Webhook in Hubpay Using Postman​

A. Create a New Postman Request​

  1. In Postman, create a new POST request.
  2. Set the URL to the registration endpoint (replace with actual API base URL): 
    https://api.example.com/v1/webhooks

B. Set Headers​

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

Replace <YOUR_JWT_TOKEN> with your actual credentials.

C. Set Body (raw, JSON)​

{
  "callbackUrl": "https://webhook.site/your-unique-id",
  "eventTypes": [
    "v1.collection.payment_request.created",
    "v1.collection.payment_request.paid"
  ]
}
  • Use your Webhook.site URL, or your ngrok HTTPS URL.
  • Specify the event types you want to receive notifications for.

D. Send the Request​

  • Click Send.
  • Expect a 201 Created response with a webhookId if registration succeeds.

3. Retrieve Your Signing Secret​

After registration, retrieve the HMAC signing secret for your webhook.

A. Create a New GET Request in Postman​

  1. Set the URL to: 
    https://api.example.com/v1/webhooks/{webhookId}/signing-secret
    Replace {webhookId} with the ID returned in step 2.

B. Set Headers​

  • Authorization: Bearer <YOUR_JWT_TOKEN>

C. Send the Request​

  • Click Send.
  • The response contains a key field — this is your signing secret. Store it securely.

4. Trigger an Event (or Simulate a Callback)​

A. Wait for Real Event​

  • Once registered, perform the action in Hubpay that triggers the webhook (e.g., a transaction event).

B. Simulate with Postman (Manual Test)​

  • To test your endpoint, you can use Postman to send a POST request directly to your Webhook.site/ngrok URL, simulating Hubpay's webhook delivery: 
    {
      "eventType": "transaction.created",
      "data": { "example": "payload" }
    }
  • In the headers, add an hmac-signature header. You can compute it using your signing secret and the raw payload body with SHA-256 HMAC (see below for signature calculation).

5. Viewing Webhook Requests​

  • On Webhook.site, you'll see all received requests in real-time, including:
    • The request body (payload).
    • All headers (look for the hmac-signature or similar).

6. Verifying the HMAC Signature​

Every webhook notification includes headers for signature verification. For the full verification process — including constructing the signed content, computing the HMAC, checking timestamps, and code examples in multiple languages — see the dedicated Verifying webhook signatures guide.

7. Tips for Testing​

  • Always use HTTPS for your webhook URLs.
  • Store your signing secret securely and do not share it.
  • If using Webhook.site, any request—real or test—will appear instantly; no code required.
  • If your server is receiving the webhook, use server logs to view and validate incoming requests and headers.
  • If you need to simulate signature mismatch, alter the payload or use the wrong key when testing.

8. Troubleshooting​

  • No webhook calls? Double-check your callback URL and ensure your server is reachable from the public internet.
  • Signature mismatch? Make sure you use the exact raw request body and the correct signing secret.
  • Unexpected or unauthorized requests? Only trust webhooks with valid HMAC signatures.

9. Cleaning Up​

  • After testing, you may want to unregister your test webhook to avoid receiving events to a temporary or public endpoint.

You have now successfully tested Hubpay webhook registration and event delivery using Postman and a public/test endpoint!