Skip to main content

Testing Webhooks

This guide covers how to test your Hubpay webhook integration end-to-end in the sandbox environment — from registering an endpoint to receiving and verifying live events.

1. Register your webhook endpoint​

Register the URL where you want to receive webhook events using the Register Webhook endpoint. Your endpoint must be publicly reachable over HTTPS.

Specify the event types you want to subscribe to. For collections, the key events are:

EventWhen it fires
v1.collection.payment_request.createdPayment request created
v1.collection.payment_request.paidFull balance received
v1.collection.payment_request.part_paidPartial payment received
v1.collection.payment_request.payment.pendingPayment initiated / deposit detected / card authorised
v1.collection.payment_request.payment.receivedFunds received / deposit confirmed / card captured
v1.collection.payment_request.payment.completedFunds settled to wallet
v1.collection.payment_request.payment.payout.initiatedAuto-payout created (if payout details configured)

See Webhook Events for the full event catalogue.

2. Retrieve your signing secret​

After registration, retrieve the HMAC signing secret for your webhook via the Get Signing Secret endpoint. Store this securely — you'll need it to verify that incoming webhook requests genuinely came from Hubpay.

3. Trigger events​

You have two options for triggering webhook events in sandbox:

Option A: Simulate a payment​

Use the Simulate Payment endpoint to trigger the full payment lifecycle. This fires real webhook events to your registered endpoint — the same events your integration will receive in production.

See Simulating Payments for a step-by-step walkthrough.

Option B: Perform a real transaction​

In sandbox, you can also trigger webhooks by completing real payment flows — for example, using test card numbers through the hosted payment page. This is useful for testing provider-specific behaviour (3DS challenges, card declines) that the simulation endpoint does not replicate.

4. Verify signatures​

Every webhook delivery includes headers for HMAC signature verification. Always verify signatures before processing webhook payloads to ensure they originated from Hubpay and haven't been tampered with.

For the full verification process — including constructing the signed content, computing the HMAC, and checking timestamps — see Verifying Webhook Signatures.

Important

Never process a webhook payload without verifying the signature first. In production, unsigned or incorrectly signed requests should be rejected with HTTP 401.

5. Delivery and retries​

Hubpay expects your endpoint to respond with an HTTP 2xx status code to acknowledge receipt. If your endpoint doesn't respond or returns an error:

  • Hubpay retries delivery using exponential backoff
  • See Retry Strategy for the full retry schedule and timing

Design your webhook handler to be idempotent — the same event may be delivered more than once if acknowledgement is lost.

Troubleshooting​

ProblemCheck
Not receiving webhooksVerify your callback URL is publicly reachable over HTTPS. Check that you've subscribed to the correct event types.
Signature verification failingEnsure you're using the exact raw request body (not parsed/re-serialised) and the correct signing secret for this webhook registration.
Duplicate eventsThis is expected behaviour — webhooks can be retried. Ensure your handler is idempotent.
Events arriving out of orderHubpay dispatches events in order but delivery is not strictly guaranteed. Use the createdAt timestamp to determine sequence, and always fetch the latest resource state via the API before acting. See Ordering and delivery guarantees.

Clean up​

After testing, consider unregistering temporary webhook endpoints via the Delete Webhook endpoint to avoid receiving events at URLs you no longer monitor.