BitBusca › Desenvolvedores › Webhooks
Em vez de perguntar a cada minuto, cadastre um endpoint HTTPS e receba o evento quando acontece: intimação nova, edital novo, empresa aberta no seu filtro, créditos acabando. Cada entrega vem assinada com HMAC-SHA256.
Hoje: Um cron perguntando à API a cada minuto, gastando processamento e ainda chegando atrasado. Com a API: Cadastre um endpoint HTTPS e receba o evento quando acontece, assinado, com até 7 tentativas em 24 horas.
Sem custo por entrega · escopo webhooks · planos a partir de R$ 19,90/mês. Chave de teste grátis.
import crypto from 'node:crypto';
// corpo cru (string), como chegou — antes de JSON.parse
function assinaturaValida(corpo, cabecalho, segredo) {
const partes = Object.fromEntries(cabecalho.split(',').map((p) => p.split('=')));
const esperado = crypto.createHmac('sha256', segredo)
.update(`${partes.t}.${corpo}`).digest('hex');
const recente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300;
return recente && partes.v1?.length === esperado.length &&
crypto.timingSafeEqual(Buffer.from(partes.v1), Buffer.from(esperado));
}POST https://seu-app.com/webhooks/bitbusca
X-BitBusca-Evento: licitacoes.edital
X-BitBusca-Entrega: ent_01J…
X-BitBusca-Assinatura: t=1793300000,v1=5f2c…
{
"id": "evt_01J…",
"tipo": "licitacoes.edital",
"criadoEm": "2026-10-29T12:00:00Z",
"ambiente": "producao",
"dados": { "alerta": "alr_…", "edital": { "id": "ed_01J…" } }
}Exemplo fictício, formato resumido. Referência completa: OpenAPI.
X-BitBusca-Evento — Qual evento chegou, para rotear sem abrir o corpo.X-BitBusca-Entrega — O id da entrega: use para não processar o mesmo evento duas vezes.X-BitBusca-Assinatura — A prova de que veio da BitBusca (HMAC com timestamp).tipo — O evento no corpo, para o seu código decidir o que fazer.ambiente — Produção ou teste: separe o que é real.dados — O que aconteceu: o alerta, o edital, a publicação ou a empresa.GET /v1/webhooks — Lista os webhooks da contaPOST /v1/webhooks — Cadastra um endpoint HTTPS e os eventosDELETE /v1/webhooks/{id} — Remove um webhookPOST /v1/webhooks/{id}/testar — Manda um teste.pingCrie um endpoint POST /webhooks/bitbusca que leia o corpo cru, confira o cabeçalho X-BitBusca-Assinatura (t=<unix>,v1=<HMAC-SHA256 hex de "t.corpo" com o segredo em BITBUSCA_WEBHOOK_SECRET>), recuse se tiver mais de 5 minutos, responda 200 rápido e processe o evento pelo campo "tipo".
Use a API da BitBusca (base https://api.bitbusca.net/api). A especificação OpenAPI está em https://api.bitbusca.net/api/v1/openapi.json.
Autentique com o cabeçalho "Authorization: Bearer <chave>", lendo a chave da variável de ambiente BITBUSCA_API_KEY.
Nunca coloque a chave no código do navegador: faça as chamadas por uma função de servidor (edge function, API route ou backend).
Trate os erros pelo campo "code" da resposta: 402 NO_CREDITS (sem créditos), 429 RATE (respeite o cabeçalho Retry-After), 429 COTA_DIARIA (teto do dia atingido), 404 NOT_FOUND (mostre "nada encontrado", não é cobrado).
Comece com a chave de teste (bk_test_…), que devolve dados fictícios e não gasta créditos.Tentamos de novo por 24 horas (1 min, 5 min, 30 min, 2 h, 6 h e 24 h) e você pode reenviar qualquer entrega pelo painel.
Confira a assinatura X-BitBusca-Assinatura com o segredo do webhook (HMAC-SHA256 de "t.corpo") e recuse eventos com mais de 5 minutos.
Não. Os avisos ao desenvolvedor vão por e-mail e webhook.
Sim: qualquer ferramenta que receba POST em HTTPS. Confira a assinatura quando a ferramenta permitir.