Webhooks
Webhooks are HTTP callback notifications sent by a payment infrastructure provider to a specified URL when specific events occur, such as a payment completing, a card being authorized, or an account balance changing. This enables real-time, event-driven integration without continuous polling.
Traditional integration polling asks the API repeatedly: 'has anything changed?' Webhooks invert this: the infrastructure provider notifies the receiving system immediately when something happens. A webhook delivers an HTTP POST request to the client's designated endpoint containing a structured JSON payload describing the event.
For payment operations, webhooks are essential. Cross-border payments settle asynchronously: a payment initiated at 9am may not settle until later that day or the following business day. Without webhooks, platforms must repeatedly poll the payment status API until settlement is confirmed. With webhooks, settlement confirmation is pushed to the platform the moment it occurs, triggering downstream processes such as inventory release, order completion, or account credit, without polling overhead.
Webhook security requires careful implementation. Signature verification, which validates an HMAC signature in the webhook header, confirms the event genuinely originated from the payment provider and was not injected by a third party. Idempotency handling ensures that duplicate webhook deliveries do not cause duplicate processing in the receiving system.
Webhooks enable event-driven payment operations: when a payout settles, the platform's reconciliation updates automatically; when a card is authorized, spend control records update in real time; when a payment fails, exception workflows trigger immediately. Webhooks transform payment operations from reactive (checking what happened) to proactive (responding when it happens).
- Webhook endpoints must be publicly accessible over HTTPS, requiring infrastructure and security configuration
- Delivery failures require retry handling: the payment provider will retry failed deliveries, requiring idempotent processing
- Signature verification is essential but often not implemented correctly
- Webhook volume at scale can be significant: high-volume programs may receive thousands of webhooks per hour
- Webhook processing failures must not block payment operations: async processing queues are recommended
A gig economy platform replacing manual payout status checks with Nium webhooks eliminates a 200-call/day API polling pattern. Webhook events for payout completion trigger automatic worker dashboard updates and accounting reconciliation. Operations team time spent on payout status inquiries drops by 85% as all status information is pushed in real time to internal systems.
Related Concepts
Nium's platform delivers webhook notifications for all key payment and card events, including payment initiated, payment completed, payment failed, card authorized, card declined, and account credited, to client-configured endpoints. Nium's webhooks include HMAC signatures for security verification and retry logic for failed deliveries.
Answers you didn't know you needed.
What is a webhook?
A webhook is a real-time HTTP notification sent by one system to another when a specific event occurs. In payments, webhooks notify your system when a payment settles, a card is used, or an account balance changes, without requiring you to poll the API for updates.
How do I receive webhooks from Nium?
You register a publicly accessible HTTPS endpoint URL with Nium. When payment events occur, Nium sends HTTP POST requests to that URL with JSON event payloads. Your endpoint must return a 200 HTTP response to confirm receipt.
What if a webhook delivery fails?
Nium retries failed webhook deliveries multiple times with increasing delays. Your system should handle duplicate deliveries idempotently, processing each unique event only once even if the webhook is received multiple times.
How do I verify a webhook is from Nium?
Nium includes an HMAC-SHA256 signature in each webhook header. By verifying this signature against your webhook secret, you can confirm the webhook was sent by Nium and has not been tampered with.
What events does Nium send webhooks for?
Nium sends webhooks for payment lifecycle events (initiated, processing, completed, failed), card authorization events (approved, declined), account events (funded, debited), and compliance events (KYC updates, compliance holds).