Guides
  1. Operação

Webhooks

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

Onde configurar

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

Configuração da conta

Campos confirmados na UI/backend do painel:

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

Ações na UI:

  • Salvar Configurações
  • Regenerar Chave HMAC (invalida a anterior)
  • Geração/visualização de token e secret com botões de copiar

Dois padrões de integração

1. Webhook da conta (painel)

Configurado em /dashboard/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

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

Entrega HTTP

ItemValor confirmado
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)

Catálogo exibido no painel

A UI lista 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.

🚧

Pendência
Nem todos os nomes do catálogo da UI e dos eventos normalizados de entrega estão unificados em um único enum público. Trate o campo event de forma tolerante e mantenha o catálogo do painel como referência operacional.

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 logue tokens, secrets ou dados jurídicos desnecessários.
  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/autos apenas após conclusão

Relacionados