Verifying & Testing Webhooks¶

Verifying incoming webhooks¶

Before trusting the contents of an inbound webhook payload, verify that it actually came from Hivemind Payments. The source collection does not document a specific verification mechanism, so treat this as an open item to confirm with Hivemind Payments. Common options for payment APIs, in rough order of preference:

• IP whitelist — restrict your webhook endpoint to only accept requests from Hivemind Payments' published IP ranges; see IP Whitelisting.

Regardless of mechanism, always re-fetch the authoritative status via Transaction Status Query or the Transactions Statement before taking an irreversible action (e.g. releasing goods) based solely on a webhook payload, until signature verification is confirmed and implemented.

Testing webhooks in sandbox¶

Sandbox is the supported way to exercise your webhook handler. Sandbox results are delivered to your result_url over real HTTP, with the same payload shape a production result has — so a handler that works here works there.

It also lets you test the deliveries that are hard to arrange on purpose:

• A failed payment's callback — initiate to 254700000001 (cancelled) or 254700000002 (insufficient funds) and confirm your handler does the right thing with a non-zero ResultCode.
• A callback that never comes — initiate to 254700000003 and confirm your system resolves the payment by status query rather than waiting forever.
• A callback that arrives late — initiate to 254700000005 and confirm a result two minutes later is still accepted, rather than landing on a payment your code has already written off.

See Sandbox Credentials & Test Numbers for the full table.

Returning a 2xx to at least one sandbox result is a go-live requirement. It is the check that catches an integration about to go live with a callback endpoint that has never actually received anything.

Testing webhooks locally¶

Since your local machine isn't reachable from the internet, use a tunneling or request-inspection tool to receive test callbacks during development:

• webhook.site — generates a temporary public URL you can inspect payloads on without running any local server. This is what the source Postman collection itself uses as an example result_url.
• ngrok — tunnels a public URL to a server running on your local machine, useful once you're ready to test your own callback handler end to end.

Suggested flow¶

1. Generate a temporary webhook.site URL (or start an ngrok tunnel to your local handler).
2. Use that URL as result_url when calling Initiate Payment in sandbox.
3. Trigger a test transaction and inspect the callback payload as it arrives.
4. Once your handler works against webhook.site output, point result_url at your ngrok tunnel and confirm your own code parses it correctly.