Webhooks
Subscribe to real-time events. Backchannel uses webhooks to notify your application when an event happens in your account.
How it works
Configuration
Define a URL in the Command Center to receive POST requests.
Trigger
An event (e.g., order payment) occurs in the Backchannel ecosystem.
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.
| Field | Type | Description |
|---|---|---|
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
| Field | Type | Description |
|---|---|---|
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
| Field | Type | Description |
|---|---|---|
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.
X-BC-Signature: sha256=a8f...92const 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
}Event Preview
Simulated event payload
{
"id": "evt_0Lx291",
"type": "order.created",
"created": 1708456200,
"data": {
"order_id": "ord_9182",
"customer": "Nike Store",
"amount": 250000,
"currency": "brl"
}
}