Webhooks

Um webhook avisa outro sistema (um ERP, uma planilha, uma automação no Zapier ou Make) sempre que algo muda no Bienna². A cada evento escolhido, o Bienna² envia um POST com os dados do registro para a URL que você informar. Abra Configurações → Integrações → Webhooks.

Só para proprietários

Membros não veem esta tela no menu. Webhooks, Chaves de API e Provedores ficam no grupo Integrações.

Plano Business

Webhooks fazem parte do plano Business (e do Enterprise e do período de teste). No Starter, o botão aparece com um cadeado e a tela mostra o aviso do plano, com o link Ver planos. Os webhooks que já existem continuam entregando e podem ser editados, pausados ou excluídos.

Lista de webhooks

A lista mostra o nome, a URL de destino, quantos eventos cada webhook recebe (passe o mouse para ver quais) e o status (Ativo ou Inativo).

Lista de webhooks

• Editar: clique no nome do webhook ou no lápis.
• Excluir: clique na lixeira e confirme. O webhook e o histórico de entregas dele são apagados, sem volta.

Cadastrar um webhook

1. Clique em Novo webhook.
2. Dê um Nome que identifique o destino, por exemplo "ERP financeiro".
3. Informe a URL de destino, começando com https:// (ou http://).
4. Marque os Eventos que devem ser enviados. É preciso escolher ao menos um.
5. Deixe o Status como Ativo e clique em Salvar webhook.

Formulário de novo webhook

Depois de salvar, o painel abre a página de edição com o aviso "Webhook criado. Copie o segredo para validar as assinaturas.". Copie o segredo e entregue a quem mantém o sistema de destino.

Eventos

Recurso	Eventos na tela	Nome técnico
Leads	Lead criado, Lead atualizado, Lead excluído	lead.created, lead.updated, lead.deleted
Clientes	Cliente criado, Cliente atualizado, Cliente excluído	client.created, client.updated, client.deleted
Contatos	Contato criado, Contato atualizado, Contato excluído	contact.created, contact.updated, contact.deleted
Produtos e serviços	Produto/Serviço criado, Produto/Serviço atualizado, Produto/Serviço excluído	product.created, product.updated, product.deleted

Mover um lead de estágio no pipeline também gera lead.updated.

Editar ou pausar um webhook

Na página Editar webhook, altere o que precisar e clique em Salvar alterações. O painel volta para a lista.

Para pausar um webhook sem apagá-lo, mude o Status para Inativo e salve.

Segredo e entregas

Na página de edição ficam o segredo e o histórico de entregas.

Segredo e entregas recentes

• Segredo (assinatura HMAC-SHA256): fica oculto. Use o olho para mostrar e o botão ao lado para copiar.
• Entregas recentes: cada envio aparece com o evento, a data e hora, o tempo de resposta e o resultado: o selo HTTP com o código devolvido pelo destino (verde para sucesso, vermelho para erro) ou Falhou, quando o destino não respondeu. Um envio repetido mostra o número da tentativa, como "2ª tentativa".
• Clique numa entrega para ver o payload enviado e a resposta do destino (ou o erro).
• A lista não se atualiza sozinha: clique em Atualizar para ver as entregas novas.

Para quem vai receber os envios

Repasse estas informações à equipe técnica do sistema de destino:

• O envio é um POST com corpo JSON:

  {
    "id": "76b2944db8644f61af1795589bc005fd",
    "event": "lead.created",
    "occurredAt": "2026-10-26T05:10:29.883Z",
    "organizationId": 1,
    "data": { "id": 7, "name": "Fernanda Dias", "company": "Lambda Têxtil", "...": "..." }
  }

• Cabeçalhos: X-Bienna-Event (o evento), X-Bienna-Delivery (o id da entrega), X-Bienna-Timestamp (o momento do envio, em segundos Unix) e X-Bienna-Signature.

• Validação: X-Bienna-Signature vale sha256= seguido do HMAC-SHA256, em hexadecimal, do texto timestamp.corpo (o valor de X-Bienna-Timestamp, um ponto e o corpo exatamente como recebido), calculado com o segredo do webhook. Se a assinatura não bater, descarte a requisição. Recuse também timestamps com mais de 5 minutos.

• Prazo: o destino deve responder em até 10 segundos, com um status 2xx.

• Novas tentativas: quando o destino demora demais, não responde ou devolve erro de servidor (5xx, além de 408 e 429), o Bienna² tenta de novo automaticamente, com o mesmo id de entrega. Outros erros 4xx não são repetidos. Cada tentativa fica registrada em Entregas recentes.

• Endereços internos: URLs que apontam para a rede interna (como localhost ou 192.168.x.x) são bloqueadas por segurança. Use um endereço público.

Checklist

• ✅ Ver a lista de webhooks
• ✅ Cadastrar um webhook (nome, URL, eventos, status)
• ✅ Editar um webhook
• ✅ Pausar (status Inativo)
• ✅ Excluir um webhook
• ✅ Mostrar e copiar o segredo
• ✅ Ver entregas recentes, payload e resposta
• ✅ Atualizar a lista de entregas
• ✅ Formato do envio e validação da assinatura
• ✅ Aviso do plano Business no Starter