Reliability/Webhooks

Webhooks

Subscribe to real-time events. Backchannel uses webhooks to notify your application when an event happens in your account.

How it works

01

Configuration

Define a URL in the Command Center to receive POST requests.

02

Trigger

An event (e.g., order payment) occurs in the Backchannel ecosystem.

03

Delivery

We send an HTTP POST with a JSON payload and a cryptographic signature.

Main Payload

All webhook events share a common top-level structure.

FieldTypeDescription
idRequired
string

Unique event identifier. Prefixed with 'evt_'.

Example: evt_0Lx291
typeRequired
string

The event type code.

Example: order.created
created_at
integer

Unix timestamp of when the event was generated.

Example: 1708456200
dataRequired
object

The actual resource payload. Varies by event type.

Event Types

Order Events

FieldTypeDescription
order.created
event

Occurs when a brand or API creates a new order object.

order.paid
event

Occurs when payment status changes to 'captured'.

order.shipped
event

Occurs when tracking information is added to the order.

Inventory Events

FieldTypeDescription
inventory.updated
event

Occurs when available stock levels change.

inventory.reallocated
event

Occurs when virtual stock is moved between nodes.

Security & Verification

Always verify that webhook requests are authentic. We sign every request using an HMAC SHA256 signature based on your webhook secret.

The Signature HeaderX-BC-Signature: sha256=a8f...92
Verification Script (Node.js)
const crypto = require('crypto');

const secret = process.env.BC_WEBHOOK_SECRET;
const payload = JSON.stringify(req.body);
const signature = req.headers['x-bc-signature'];

const hmac = crypto.createHmac('sha256', secret);
const digest = 'sha256=' + hmac.update(payload).digest('hex');

if (signature === digest) {
  // Request is authentic
}