Skip to main content

​
Webhooks Introduction

Webhooks enable your application to receive instant notifications about important events, making it easy to automate workflows and keep external systems in sync with Carbon’s API.

​
What Are Webhooks?

Webhooks are HTTP callbacks triggered by specific events in your Carbon account. When an event occurs, Carbon sends a POST request to your configured webhook URL, allowing your server to process the event in real time.

​
How Webhooks Work

1

Configure Your Webhook URL

Set your webhook endpoint using the API or dashboard. Make sure your server is ready to accept POST requests.
2

Event Triggered

When a relevant event occurs (e.g., a transaction is completed), Carbon automatically sends a POST request to your webhook URL with event details.
3

Acknowledge Receipt

Your server should respond with a 2xx status code to confirm successful receipt. If not, Carbon may retry delivery.

​
Key Features

Receive immediate updates for events such as transactions, account changes, and more.
Easily update your webhook URL or select which events you want to subscribe to.
Each webhook request includes a HMAC-SHA256 signature in the X-Carbon-Baas-Signature header for verification. The signature is calculated by JSON-encoding the payload and hashing it with your secret key. Always validate the signature to ensure authenticity and prevent tampering.

​
Example Webhook Events

Some common events you can subscribe to:
  • account.incoming-transaction
  • account.outgoing-transaction
For a full list and details, see the Webhook Events documentation.

​
Best Practices

Always verify the signature included in webhook requests to confirm they originate from Carbon.

​
How Signature Verification Works

Carbon signs each webhook with HMAC-SHA256 using your webhook secret and sends the signature in the X-Carbon-Baas-Signature header.Signature Generation:
  1. JSON-encode the webhook payload
  2. Create HMAC-SHA256 hash using your secret key
  3. The result is sent in the X-Carbon-Baas-Signature header

​
Finding Your Webhook Secret

Your webhook secret can be found in your Carbon dashboard on the Developer page.

​
Implementation Examples

<?php

function verifyWebhookSignature($payload, $signature, $secret) {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expectedSignature, $signature);
}

// Usage
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CARBON_BAAS_SIGNATURE'];
$secret = 'your-webhook-secret-from-dashboard';

if (!verifyWebhookSignature($payload, $signature, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// Process webhook data...

​
Security Best Practices

  • Use constant-time comparison: Always use hash_equals() (PHP), crypto.timingSafeEqual() (Node.js), hmac.compare_digest() (Python), or equivalent functions to prevent timing attacks
  • Validate before processing: Never process webhook data before verifying the signature
  • Keep secrets secure: Store your webhook secret as an environment variable, never in your codebase
  • Use HTTPS: Always use HTTPS endpoints to protect data in transit
If your server does not respond with a 2xx status code, Carbon will retry delivery up to 3 times. Ensure your endpoint can handle duplicate events safely.

​
Manual Resend Options

If automatic retries fail, you can manually resend webhook events:
  • Dashboard: Navigate to the Nexus menu in your Carbon dashboard to resend failed webhooks
  • API: Use the Resend Webhook Event API endpoint for programmatic resending
This gives you full control over webhook delivery and allows you to retry specific events as needed.
Set up logging and monitoring for your webhook endpoint to track received events and troubleshoot issues quickly.

​
Troubleshooting & Support

If you experience issues with webhook delivery or event processing, check your server logs and ensure your endpoint is publicly accessible. For further assistance, refer to the Error Handling documentation or contact Carbon support.