Eventos e webhooks

Em breve, o BIX vai avisar o seu sistema quando uma tarefa termina ou quando um dado muda, sem você precisar ficar perguntando.

O resto deste portal mostra o seu sistema chamando o BIX. Esta página mostra o contrário: o BIX chamando o seu sistema para avisar que algo aconteceu. Por exemplo:

• uma tarefa terminou: a contagem foi encerrada, a auditoria de ruptura foi respondida, a conferência de validade acabou;
• uma tarefa mudou de situação: foi criada, começou na loja, foi cancelada;
• um dado mudou: uma rebaixa foi aprovada ou encerrada, uma validade mudou de cor, uma ruptura foi confirmada na gôndola.

Com o aviso, o seu sistema reage na hora, em vez de consultar a API de tempos em tempos.

sequenceDiagram
    participant Loja as Loja (app)
    participant BIX as BIX
    participant Voce as Seu sistema
    Loja->>BIX: encerra a contagem
    BIX->>Voce: POST /seu-endereco (evento task.finished)
    Voce-->>BIX: 200 (recebido)
    Voce->>BIX: GET na API pública (o detalhe)

O aviso é um sinal, não o dado

O evento diz o que mudou e onde buscar, e traz um resumo para você decidir se interessa. O detalhe completo vem da API pública, lido na hora em que você for tratar o evento. Assim o seu sistema sempre trabalha com a versão mais recente, mesmo que dois avisos cheguem fora de ordem.

{
  "id": "evt_8f2c1a0e5b7d4c19",
  "type": "task.finished",
  "occurred_at": "2026-11-10T18:42:07-03:00",
  "environment": "demonstracao.appbix.com.br",
  "data": {
    "task": {"id": 5202, "module": "count", "status": "finished", "previous_status": "in_progress"},
    "store": {"id": 12, "code": "0012"}
  }
}

Tipos de evento

O campo module da tarefa usa os mesmos códigos de módulo da API: count (Contagem), rupture (Ruptura), expiry (Validade), wms (WMS) e checklist.

Como o seu endpoint deve responder

• Receba um POST com o evento em JSON e responda 2xx em até 10 segundos. Guarde o evento e processe depois: quem processa dentro da chamada estoura o tempo e recebe o mesmo aviso de novo.
• Qualquer resposta fora de 2xx, ou sem resposta, vira nova tentativa, com intervalos crescentes (1 minuto, 5 minutos, 30 minutos, 2 horas…) por até 24 horas.
• O mesmo evento pode chegar mais de uma vez, e eventos diferentes podem chegar fora de ordem. Descarte o id que você já tratou e leia o estado atual na API.

Como saber que o aviso veio do BIX

Toda chamada leva três cabeçalhos:

Confira a assinatura antes de confiar no conteúdo, e recuse avisos com o timestamp muito antigo (mais de 5 minutos), para ninguém reenviar um aviso capturado.

import hashlib, hmac, time

def aviso_do_bix(corpo: bytes, assinatura: str, segredo: str) -> bool:
    partes = dict(p.split("=", 1) for p in assinatura.split(","))
    if abs(time.time() - int(partes["t"])) > 300:
        return False
    esperado = hmac.new(segredo.encode(), f'{partes["t"]}.'.encode() + corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, partes["v1"])

Como cadastrar

O endereço que recebe os avisos, os tipos de evento de interesse e o segredo da assinatura são definidos com o administrador do BIX do cliente, na implantação da integração. Um endereço por integrador, só com https.