Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.carbn.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Carbn webhooks allow you to receive real-time notifications when payment events occur in your Carbn account. This guide covers registering, implementing, and enabling webhooks using Carbn’s REST API.

​
Prerequisites

  • A Carbn account with API access
  • Carbn API credentials (API key)
  • HTTPS endpoint with valid certificate
  • Development environment with your preferred language

​
Step 1: Create Your Webhook Endpoint

First, create an endpoint on your server to receive webhook notifications.

​
Webhook Payload Structure

All webhook payloads follow this structure: 
{
  "status": "PAYMENT_PROCESSED",
  "txn_id": "da4ac399-ed76-42f3-ba29-e4f4b7e2b46c",
  "user_id": "38758d6e-05f7-46a2-86d1-5ab45a49bc64"
}

​
HTTP Headers

When Carbn sends webhook events, your endpoint will receive these headers:
  • Content-Type: application/json
  • User-Agent: Java/17.0.14
  • X-Webhook-Event-Id: Unique identifier for this delivery attempt
  • X-Webhook-Id: Identifier of the webhook configuration
  • X-Webhook-Signature: Base64 encoded signature for payload verification

​
Example Webhook Handler

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhooks/carbn', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const eventId = req.headers['x-webhook-event-id'];
  const webhookId = req.headers['x-webhook-id'];
  const payload = req.body;
  
  // Verify webhook signature (recommended)
  if (!verifySignature(JSON.stringify(payload), signature)) {
    return res.status(401).send('Unauthorized');
  }
  
  // Handle idempotency using event ID
  if (isEventProcessed(eventId)) {
    return res.status(200).send('Already processed');
  }
  
  const { status, txn_id, user_id } = payload;
  
  switch (status) {
    case 'PAYMENT_PROCESSED':
      handlePaymentProcessed(txn_id, user_id);
      break;
    case 'PAYMENT_FAILED':
      handlePaymentFailed(txn_id, user_id);
      break;
    default:
      console.log('Unknown payment status:', status);
  }
  
  // Mark event as processed
  markEventProcessed(eventId);
  res.status(200).send('OK');
});

function verifySignature(payload, signature) {
  // Carbn uses RSA signature verification with base64 encoded signature
  // This is a simplified example - implement proper RSA verification
  const publicKey = process.env.CARBN_PUBLIC_KEY;
  
  try {
    const verify = crypto.createVerify('SHA256');
    verify.update(payload);
    const signatureBuffer = Buffer.from(signature, 'base64');
    return verify.verify(publicKey, signatureBuffer);
  } catch (error) {
    console.error('Signature verification failed:', error);
    return false;
  }
}

function handlePaymentProcessed(txnId, userId) {
  console.log(`Payment ${txnId} processed for user ${userId}`);
  // Update your database, notify user, etc.
}

function handlePaymentFailed(txnId, userId) {
  console.log(`Payment ${txnId} failed for user ${userId}`);
  // Handle payment failure, notify user, etc.
}

​
Step 2: Register Your Webhook

Once your endpoint is ready, register it with Carbn. You must specify both url and event_category. Important: Webhooks are created with status: "disabled" by default and must be enabled separately.

​
Webhook event categories

Choose one event category per webhook. Each webhook receives only events for its category:
Event categoryDescription
ONRAMP_TRANSACTION_STATUSOnramp (fiat-to-crypto) transfer status updates (e.g. initiated, funds received, payment processed).
OFFRAMP_TRANSACTION_STATUSOfframp (crypto-to-fiat) transfer status updates.
PAYOUTPayout status updates for local currency payouts (e.g. INITIATED, PAYOUT_PROCESSED, FAILED).
USER_STATUS_UPDATEUser KYC and onboarding status changes (e.g. under_review, active, rejected, incomplete).
CUSTODY_WALLET_TRANSACTIONCustody wallet transfer status updates (e.g. initiated, in_review, completed).
curl --request POST \
  --url https://api.carbnconnect.com/onboarding/api/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "url": "https://your-app.com/webhooks/carbn",
    "event_category": "ONRAMP_TRANSACTION_STATUS"
  }'
Response: 
{
  "id": "f79bc473-d45d-4026-86ec-864d4d047905",
  "url": "https://your-app.com/webhooks/carbn",
  "status": "disabled",
  "created_at": "2024-01-15T10:30:00Z"
}
Save the webhook_id from the response - you’ll need it to enable the webhook.

​
Step 3: Enable Your Webhook

Before your webhook can receive events, you must enable it using the PUT endpoint: 
curl --request PUT \
  --url https://api.carbnconnect.com/onboarding/api/v1/webhooks/{webhook_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "url": "https://your-app.com/webhooks/carbn",
    "status": "enabled"
  }'

​
Payment Status Events

Carbn webhooks notify you when payment statuses change. The main status values are:
  • PAYMENT_PROCESSED - Payment has been successfully processed
  • PAYMENT_FAILED - Payment processing failed
Example payload: 
{
  "status": "PAYMENT_PROCESSED",
  "txn_id": "da4ac399-ed76-42f3-ba29-e4f4b7e2b46c",
  "user_id": "38758d6e-05f7-46a2-86d1-5ab45a49bc64"
}

​
What’s Next?

Webhook Verification

Learn how to verify webhook authenticity using RSA signatures
Your webhook is now configured to receive real-time payment notifications from Carbn. Next, implement proper signature verification to ensure webhook security.