Pular para o conteúdo principal

Webhooks

Webhooks permitem que a BuscaProcessos envie eventos para sua aplicação quando há novidades em monitoramentos, atualizações e fluxos assíncronos.

Eles representam o salto entre consultar periodicamente e operar por evento. Em vez de manter rotinas perguntando se algo mudou, sua aplicação recebe a novidade e pode abrir uma tarefa, atualizar um CRM, notificar uma equipe ou iniciar outro fluxo automaticamente.

O que você ganha com webhooks​

  • menos polling e menos verificações sem mudança;
  • reação automática a eventos relevantes;
  • integração com filas, CRMs, ERPs, mensageria e ferramentas no-code;
  • rastreabilidade por identificador de entrega;
  • processamento assíncrono sem bloquear a experiência do usuário;
  • base para jornadas contínuas de acompanhamento processual.

Onde configurar​

A tela possui abas de configuração, teste, logs e monitoramentos.

Configuração da conta​

No Console API, configure:

CampoFunção
URL do webhookEndpoint HTTPS do seu receptor
Token BearerEnviado como Authorization: Bearer ... quando configurado
Chave secreta HMAC SHA-256Usada para X-BuscaProcessos-Signature
Formato do payloadNORMALIZED, RAW ou BOTH
AtivoLiga/desliga a entrega
Eventos habilitadosLista selecionável no painel

No Console API, você pode:

  • Salvar Configurações
  • Regenerar Chave HMAC (invalida a anterior)
  • Gerar, visualizar e copiar token e segredo HMAC

Dois padrões de integração​

1. Webhook da conta (painel)​

Configurado em Webhooks e usado para entregas centralizadas e callbacks de operações que dependem da configuração da conta (enviar_callback / send_callback).

2. webhook_url por monitoramento​

Alguns recursos aceitam webhook_url HTTPS no body da API, por exemplo:

  • monitoramento de intimações por OAB
  • radar de novos processos
  • monitoramento de publicações do STF e da Justiça Eleitoral
  • monitoramento de processos administrativos por NUP

A URL deve ser HTTPS. URL inválida retorna erro como INVALID_WEBHOOK_URL.

Entrega HTTP​

ItemComportamento
MétodoPOST
Content-Typeapplication/json
User-AgentBuscaProcessos-Webhook/1.0
Timeout10 segundos
Sucessoresposta HTTP 2xx
Retrybackoff exponencial em minutos (min(120, 2^attempt))

Headers de entrega​

Content-Type: application/json
User-Agent: BuscaProcessos-Webhook/1.0
X-BuscaProcessos-Event: <evento>
X-BuscaProcessos-Delivery-Id: <id-da-entrega>
X-BuscaProcessos-Timestamp: <unix-seconds>
Authorization: Bearer <token-configurado>          # se configurado
X-BuscaProcessos-Signature: sha256=<hmac-hex>      # se configurado

Payload normalizado (exemplo)​

{
  "id": "evt_01HXYZ1234567890",
  "event": "novo_processo",
  "source": "BUSCAPROCESSOS",
  "created_at": "2026-07-10T13:00:00.000Z",
  "data": {
    "numeroCnj": "0000000-00.2026.8.26.0000",
    "tribunal": "TJSP"
  }
}

Com formato BOTH, o payload também pode incluir o objeto raw.

Eventos​

Eventos citados no processamento/documentação técnica​

Incluem, entre outros:

  • novo_processo
  • nova_movimentacao
  • processo_encontrado
  • processo_nao_encontrado
  • processo_verificado
  • atualizacao_processo_concluida
  • atualizacao_concluida (legado)
  • publicacao_judicial_nova

Catálogo exibido no painel​

O Console API disponibiliza eventos de diário, tribunal e buscas assíncronas, por exemplo:

  • diario_movimentacao_nova
  • movimentacao_nova
  • novo_processo_envolvido
  • resultado_processo_async
  • resultado_busca_oab_async

A lista efetiva entregue depende dos eventos habilitados na conta e do tipo de monitoramento.

📘 Compatibilidade de eventos
Trate o campo event de forma tolerante e use o catálogo disponível no Console API para configurar as entregas da sua conta.

Validação de assinatura (Node.js)​

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/buscaprocessos", async (req, res) => {
  const rawBody = req.body.toString("utf8");
  const secret = process.env.BUSCAPROCESSOS_WEBHOOK_SECRET ?? "";
  const received = req.header("X-BuscaProcessos-Signature");

  if (secret && received) {
    const digest = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
    const expected = `sha256=${digest}`;
    if (
      received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
    ) {
      return res.sendStatus(401);
    }
  }

  const event = JSON.parse(rawBody);
  const eventId = event.id ?? req.header("X-BuscaProcessos-Delivery-Id");
  // deduplicar e enfileirar
  void eventId;
  return res.sendStatus(204);
});

Valide o HMAC sobre o corpo bruto, antes de re-serializar o JSON.

Boas práticas do receptor​

  1. Responda 2xx rapidamente.
  2. Processe em fila.
  3. Seja idempotente (mesmo evento pode ser reenviado).
  4. Deduplique por id e X-BuscaProcessos-Delivery-Id.
  5. Não registre tokens, segredos ou dados jurídicos desnecessários em logs.
  6. Exija HTTPS.
  7. Use o histórico de entregas do painel para diagnosticar falhas e reenviar quando disponível.

Operações assíncronas com polling​

Se não houver webhook configurado, use o endpoint de status retornado pela operação (por exemplo, status de atualização de processo) com polling finito.

Exemplo de fluxo:

POST /v1/processos/cnj/{cnj}/solicitar-atualizacao
  → GET /v1/processos/cnj/{cnj}/status-atualizacao
  → listar documentos públicos apenas após conclusão

Relacionados​