Configure Webhooks

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.
}

from flask import Flask, request, jsonify
import base64
import json
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization

app = Flask(__name__)
processed_events = set()

@app.route('/webhooks/carbn', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    event_id = request.headers.get('X-Webhook-Event-Id')
    webhook_id = request.headers.get('X-Webhook-Id')
    
    payload = request.get_data()
    
    # Verify webhook signature (recommended)
    if not verify_signature(payload, signature):
        return jsonify({'error': 'Unauthorized'}), 401
    
    # Handle idempotency
    if event_id in processed_events:
        return jsonify({'status': 'already processed'}), 200
    
    data = request.json
    status = data.get('status')
    txn_id = data.get('txn_id')
    user_id = data.get('user_id')
    
    if status == 'PAYMENT_PROCESSED':
        handle_payment_processed(txn_id, user_id)
    elif status == 'PAYMENT_FAILED':
        handle_payment_failed(txn_id, user_id)
    else:
        print(f'Unknown payment status: {status}')
    
    # Mark event as processed
    processed_events.add(event_id)
    return jsonify({'status': 'success'}), 200

def verify_signature(payload, signature):
    try:
        # Load your Carbn public key
        public_key_pem = os.environ['CARBN_PUBLIC_KEY']
        public_key = serialization.load_pem_public_key(public_key_pem.encode())
        
        # Decode the base64 signature
        signature_bytes = base64.b64decode(signature)
        
        # Verify the signature
        public_key.verify(
            signature_bytes,
            payload,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except Exception as e:
        print(f'Signature verification failed: {e}')
        return False

def handle_payment_processed(txn_id, user_id):
    print(f"Payment {txn_id} processed for user {user_id}")
    # Update your database, notify user, etc.

def handle_payment_failed(txn_id, user_id):
    print(f"Payment {txn_id} failed for user {user_id}")
    # 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 category	Description
`ONRAMP_TRANSACTION_STATUS`	Onramp (fiat-to-crypto) transfer status updates (e.g. initiated, funds received, payment processed).
`OFFRAMP_TRANSACTION_STATUS`	Offramp (crypto-to-fiat) transfer status updates.
`PAYOUT`	Payout status updates for local currency payouts (e.g. INITIATED, PAYOUT_PROCESSED, FAILED).
`USER_STATUS_UPDATE`	User KYC and onboarding status changes (e.g. under_review, active, rejected, incomplete).
`CUSTODY_WALLET_TRANSACTION`	Custody 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"
  }'

const response = await fetch('https://api.carbnconnect.com/onboarding/api/v1/webhooks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<api-key>'
  },
  body: JSON.stringify({
    url: "https://your-app.com/webhooks/carbn",
    event_category: "ONRAMP_TRANSACTION_STATUS"
  })
});

const webhook = await response.json();
console.log('Webhook registered:', webhook.id);

import requests

headers = {
    'Content-Type': 'application/json',
    'x-api-key': '<api-key>'
}

data = {
    "url": "https://your-app.com/webhooks/carbn",
    "event_category": "ONRAMP_TRANSACTION_STATUS"
}

response = requests.post(
    'https://api.carbnconnect.com/onboarding/api/v1/webhooks',
    headers=headers,
    json=data
)

webhook = response.json()
print(f"Webhook registered: {webhook['id']}")

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"
  }'

const response = await fetch(`https://api.carbnconnect.com/onboarding/api/v1/webhooks/${webhookId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<api-key>'
  },
  body: JSON.stringify({
    url: "https://your-app.com/webhooks/carbn",
    status: "enabled"
  })
});

const webhook = await response.json();
console.log('Webhook enabled:', webhook.status);

import requests

headers = {
    'Content-Type': 'application/json',
    'x-api-key': '<api-key>'
}

data = {
    "url": "https://your-app.com/webhooks/carbn",
    "status": "enabled"
}

response = requests.put(
    f'https://api.carbnconnect.com/onboarding/api/v1/webhooks/{webhook_id}',
    headers=headers,
    json=data
)

webhook = response.json()
print(f"Webhook status: {webhook['status']}")

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.

Home

Getting started

Network and Global Coverage

Prerequisites

Step 1: Create Your Webhook Endpoint

Webhook Payload Structure

HTTP Headers

Example Webhook Handler

Step 2: Register Your Webhook

Webhook event categories

Step 3: Enable Your Webhook

Payment Status Events

What’s Next?

Webhook Verification

​Prerequisites

​Step 1: Create Your Webhook Endpoint

​Webhook Payload Structure

​HTTP Headers

​Example Webhook Handler

​Step 2: Register Your Webhook

​Webhook event categories

​Step 3: Enable Your Webhook

​Payment Status Events

​What’s Next?

Webhook Verification

Prerequisites

Step 1: Create Your Webhook Endpoint

Webhook Payload Structure

HTTP Headers

Example Webhook Handler

Step 2: Register Your Webhook

Webhook event categories

Step 3: Enable Your Webhook

Payment Status Events

What’s Next?