Webhooks

Webhooks invertem o sentido da integração: em vez de a sua aplicação perguntar à API se algo mudou, o bitERP avisa você assim que a mudança acontece. Você registra uma URL HTTPS, escolhe os eventos que interessam e passa a receber um POST assinado a cada ocorrência.

É a alternativa recomendada ao polling. Uma rotina que chama GET /sales-orders de minuto em minuto gasta requisições, atrasa a reação e ainda perde alterações que aconteceram e foram desfeitas entre duas leituras. Com webhooks você reage ao fato, não à varredura.

Como funciona

1. Alguém altera um recurso no bitERP — pelo painel, pela API de Integrações, pelo MCP ou por uma automação interna.
2. O bitERP identifica que a mudança corresponde a um evento assinado pelo seu endpoint.
3. Uma entrega (delivery) é criada e enviada como POST para a sua URL, com assinatura HMAC.
4. O seu servidor responde 2xx. Se não responder, o bitERP repete a entrega com intervalos crescentes.
5. O payload identifica o que mudou, não o estado do recurso — você busca os dados atuais via API de Integrações.

Configurar um endpoint

1. Acesse o painel do bitERP em app.biterp.ai.
2. Navegue até Configurações > WebHooks.
3. Clique em Novo Webhook de saída.
4. Informe um nome (identificação interna) e a URL que vai receber os POST.
5. Selecione os eventos que deseja assinar — ver Eventos.
6. Salve. O signing secret é exibido uma única vez: copie e guarde em local seguro.

O secret tem o formato whsec_ seguido de 64 caracteres hexadecimais e é a chave usada para verificar a assinatura de cada entrega. Se você perdê-lo, é possível gerar um novo pelo painel, em Trocar segredo — o secret anterior deixa de valer imediatamente, então atualize a sua aplicação logo em seguida.

Requisitos da URL

A validação acontece no cadastro e de novo antes de cada entrega. Um domínio que passe a apontar para um endereço interno depois do cadastro tem as entregas recusadas — o que conta como falha e alimenta o circuit breaker.

Testar a conexão

Na tela do endpoint, a ação Testar conexão envia imediatamente um POST assinado com o evento webhook-endpoints.test e mostra o status HTTP, o corpo da resposta e o tempo de resposta. É a forma mais rápida de validar que a URL está acessível e que a sua verificação de assinatura funciona.

O teste é síncrono e avulso: não gera uma entrega, não aparece no histórico e não conta para as retentativas nem para o circuit breaker.

Status do endpoint

Ao reativar um endpoint que estava desativado, o bitERP faz um backfill automático da janela em que ele esteve fora, gerando as entregas que não chegaram a existir. Você recebe os eventos atrasados sem precisar de nenhuma ação.

Limites e garantias

Próximos passos