Events

Webhooks

Receive real-time notifications for events in your Nexbic account. Webhooks enable your application to react to changes instantly.

Event Types

All Events

Every webhook event includes the event type, a unique ID, the relevant data, and an idempotency key.

wallet.credit.added

Credits were added to a wallet

{ "wallet_id": "wlt_...", "amount": 1000, "balance": 5000 }

wallet.credit.deducted

Credits were deducted from a wallet

{ "wallet_id": "wlt_...", "amount": 250, "balance": 4750 }

wallet.transfer.sent

A transfer was initiated from a wallet

{ "from": "wlt_...", "to": "wlt_...", "amount": 500, "status": "completed" }

wallet.transfer.received

A transfer was received in a wallet

{ "from": "wlt_...", "to": "wlt_...", "amount": 500, "status": "completed" }

auth.user.created

A new user account was created

{ "user_id": "usr_...", "email": "user@example.com" }

auth.session.created

A new session was created

{ "session_id": "nxb_ses_...", "user_id": "usr_..." }

auth.session.revoked

A session was revoked

{ "session_id": "nxb_ses_...", "reason": "logout" }

Setup

Setting Up Webhooks

Configure a webhook endpoint in your Nexbic dashboard to start receiving events.

TypeScript SDK typescript

// Create a webhook endpoint via the API
const webhook = await nexbic.webhooks.create({
  url: "https://yourapp.com/api/webhooks/nexbic",
  events: ["wallet.credit.added", "wallet.transfer.sent"],
  description: "Production webhook"
});

console.log(webhook.secret); // "whsec_..." - save this for verification

curl bash

curl -X POST https://api.nexbic.dev/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nxb_sk_..." \
  -d '{
    "url": "https://yourapp.com/api/webhooks/nexbic",
    "events": ["wallet.credit.added", "wallet.transfer.sent"]
  }'

Security

Verifying Signatures

Every webhook request includes a signature header. Verify it to ensure the event came from Nexbic.

Signature verification typescript

// Verify webhook signature in your endpoint
import { verifyWebhookSignature } from "@nexbic/sdk";

export async function POST(request) {
  const payload = await request.text();
  const signature = request.headers.get("x-nexbic-signature");
  const secret = process.env.NEXBIC_WEBHOOK_SECRET;

  const isValid = verifyWebhookSignature(payload, signature, secret);
  
  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(payload);
  // Handle the event
  return new Response("OK", { status: 200 });
}

Reliability

Retry Logic

If your endpoint does not respond with a 2xx status, Nexbic retries the delivery with exponential backoff.

Attempt 1

Immediate delivery

0s delay

Attempt 2

After 10 seconds

10s delay

Attempt 3

After 60 seconds

60s delay

Attempt 4

After 5 minutes

5m delay

Attempt 5

After 30 minutes

30m delay

Dropped

Event is discarded

After 5 failures

Example

Webhook Handler

A complete example of a webhook endpoint that handles wallet events.

Next.js handler typescript

// Full webhook handler example (Next.js App Router)
export async function POST(request: Request) {
  const payload = await request.text();
  const sig = request.headers.get("x-nexbic-signature")!;
  
  if (!verifyWebhookSignature(payload, sig, process.env.WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(payload);

  switch (event.type) {
    case "wallet.credit.added":
      await notifyUser(event.data.wallet_id, "Credits added!");
      break;
    case "wallet.transfer.sent":
      await updateTransferStatus(event.data);
      break;
    default:
      console.log("Unhandled event type:", event.type);
  }

  return new Response("OK", { status: 200 });
}

Stay in sync with your data

Webhooks give you real-time visibility into every event happening in your Nexbic account.

API Reference