Webhooks

Configure a URL

Pelo painel, em Chaves de API > Webhook de monitoramento, ou pela API:

curl -X PUT "https://consultadeprocessos.com.br/api/partner/v2/webhook" \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://seu-sistema.com.br/webhooks/processos"}'

A resposta da criação traz o secret. Ele aparece uma única vez. Use Enviar teste no painel (ou POST /api/partner/v2/webhook/test) para conferir a integração.

O que chega

Cada evento é um POST com corpo JSON:

{
  "id": "cm9b7x1y20003kq45mnop6789",
  "event": "movement.created",
  "createdAt": "2026-10-15T09:15:02.000Z",
  "data": {
    "monitoring": { "id": "1842", "cnj": "00012347120248260100", "instance": "1", "externalId": "pasta-4471" },
    "event": {
      "id": "cm9a1b2c30001xy12abcd3456",
      "type": "movement",
      "cnj": "00012347120248260100",
      "instance": "1",
      "date": "2026-10-14T00:00:00.000Z",
      "capturedAt": "2026-10-15T09:12:44.000Z",
      "title": "Conclusos para despacho",
      "description": "Conclusos para despacho"
    }
  }
}

Eventos enviados:

• movement.created: andamento novo no tribunal.
• publication.created: publicação nova no Diário de Justiça (vem com o bloco publication).
• monitoring.created e monitoring.deleted: um processo entrou ou saiu do monitoramento.
• monitoring.paused: a renovação de 30 dias não encontrou saldo na carteira. Recarregue e cadastre o processo de novo.
• ping: evento de teste.

Andamentos com data de mais de 30 dias antes da captura (por exemplo, o histórico de um processo recém-cadastrado) não geram webhook. O histórico completo fica em GET /api/partner/v2/monitorings/{id}/events.

Valide a assinatura

Cada POST traz os cabeçalhos:

• X-Webhook-Id: identificador da entrega (igual ao id do corpo).
• X-Webhook-Event: nome do evento.
• X-Webhook-Signature: t=<timestamp>,v1=<assinatura>.

A assinatura é o HMAC-SHA256, em hexadecimal, de <timestamp>.<corpo bruto> com o seu segredo. Exemplo em Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

function isValid(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.v1 || age > 300) return false;
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1, "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Use o corpo bruto, antes de converter para JSON. Recuse entregas com mais de 5 minutos para evitar reenvio de requisições antigas.

Responda rápido

Responda com qualquer status 2xx em até 10 segundos e faça o processamento depois, em fila. Sem 2xx, tentamos de novo após 1 min, 5 min, 30 min, 2 h, 12 h e 24 h. Depois disso a entrega fica como failed e pode ser reenviada pelo painel ou por POST /api/partner/v2/webhook/deliveries/{id}/retry.

A mesma entrega pode chegar mais de uma vez. Guarde o X-Webhook-Id e ignore repetições.