Confiabilidade/Webhooks

Webhooks

Assine eventos em tempo real. O Backchannel usa webhooks para notificar seu aplicativo quando um evento ocorre em sua conta.

Como funciona

Configuração

Defina uma URL no Command Center para receber solicitações POST.

Gatilho

Um evento (ex: pagamento de pedido) ocorre no ecossistema Backchannel.

Entrega

Enviamos um HTTP POST com um payload JSON e uma assinatura criptográfica.

Payload Principal

Todos os eventos de webhook compartilham uma estrutura comum de alto nível.

Field	Type	Description
`id`Required	string	Identificador único do evento. Prefixado com 'evt_'. Example: evt_0Lx291
`type`Required	string	O código do tipo de evento. Example: order.created
`created_at`	integer	Unix timestamp de quando o evento foi gerado. Example: 1708456200
`data`Required	object	O payload real do recurso. Varia de acordo com o tipo de evento.

Tipos de Evento

Eventos de Pedido

Field	Type	Description
`order.created`	event	Ocorre quando uma marca ou API cria um novo objeto de pedido.
`order.paid`	event	Ocorre quando o status do pagamento muda para 'captured'.
`order.shipped`	event	Ocorre quando informações de rastreamento são adicionadas ao pedido.

Eventos de Estoque

Field	Type	Description
`inventory.updated`	event	Ocorre quando os níveis de estoque disponíveis mudam.
`inventory.reallocated`	event	Ocorre quando o estoque virtual é movido entre os nós.

Segurança e Verificação

Sempre verifique se as solicitações de webhook são autênticas. Assinamos cada solicitação usando uma assinatura HMAC SHA256 baseada no seu segredo de webhook.

O Cabeçalho de AssinaturaX-BC-Signature: sha256=a8f...92

Script de Verificação (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) {
  // Solicitação é autêntica
}

Prévia do Evento

Payload de evento simulado

Payload

{
  "id": "evt_0Lx291",
  "type": "order.created",
  "created": 1708456200,
  "data": {
    "order_id": "ord_9182",
    "customer": "Nike Store",
    "amount": 250000,
    "currency": "brl"
  }
}