Webhooks

Webhooks are the real-time event delivery mechanism of the CleverCards API. Instead of polling the API for changes, your system can register a webhook endpoint to automatically receive notifications whenever key events occur—such as when a card token is created, a card is frozen, or funds are added to a card account.

From a business perspective, webhooks enable seamless integration and automation. They allow your applications to react instantly to platform activity: update internal systems, trigger downstream workflows, or notify end users, all without delay.

Capabilities

Event Subscription: Register one or more webhook endpoints and specify which event types (e.g., CARD_TOKEN_CREATED, CARD_FREEZE_REQUESTED, CARD_ACCOUNT_FUNDED) you want to consume.
Secure Delivery: Configure webhook security schemes—such as API key, bearer token, or base64-encoded credentials—to authenticate incoming requests and protect against unauthorized traffic.
Reliable Notifications: Receive structured JSON payloads that provide all the necessary context to reconcile state changes in your own systems. Your endpoint can quickly acknowledge with a 2xx response while processing heavier workloads asynchronously.
Granular Control: Manage subscriptions through the API (create, update, delete, list) to adapt as your integration needs evolve.

Why It Matters

Webhooks transform the API from a pull-based integration into a push-based ecosystem. This ensures that your systems are always up-to-date without inefficient polling, reduces latency for critical workflows (like fraud control or fund reconciliation), and minimizes operational overhead.

They are particularly powerful for:

Operations & Risk: Automatically freeze accounts, escalate alerts, or trigger compliance reviews based on cardholder or card status events.
Finance & Accounting: Reconcile transactions and balances in real time as funds are added or removed.
User Engagement: Instantly notify customers when tokens are delivered, cards are activated, or balances change.

Best Practices

Always validate the authenticity of the request using your chosen security scheme.
Respond quickly with a 2xx status and handle business logic asynchronously.
Implement idempotency and retry tolerance, since events may be resent if delivery fails.