Skip to main content
Card events are delivered as HTTP POST requests to the webhook URL you set on your dashboard or per card at creation. Each delivery is signed, retried on failure, and possibly duplicated, so a correct handler does three things: verify, de-duplicate, acknowledge. The payload envelope and the full event catalog are on Webhook events.

Verify the signature

Compute HMAC-SHA512 over the raw request body using your webhook secret, and compare it to x-bitnob-signature in constant time. Reading the parsed JSON and re-serializing it will not match; verify the exact bytes received.
Reference implementation and secrets guidance: Verifying events.

Handle delivery semantics

If your firewall restricts inbound traffic, allowlist the published Source IPs, but only as a second layer: any host can spoof a source address, so the signature is the check that counts. Always use HTTPS, and keep the secret out of client code and repositories.

Test your endpoint

  • Trigger real test events end to end from the sandbox environment.
  • Replay captured payloads with curl or Postman against your local handler, signing them with your test secret.
  • Tunnel to localhost with a tool like ngrok while developing, and keep tunnels out of production configuration.