Webhooks - Documentação

Os webhooks permitem que sua aplicação receba notificações automáticas sempre que eventos importantes acontecerem dentro do JuriChat. Com eles, você pode integrar CRMs, automações, ERPs, planilhas, bots e sistemas internos em tempo real.

Os endpoints relacionados à criação e gerenciamento de webhooks estão disponíveis em API Reference.

Como funciona

Quando um evento configurado acontece, o JuriChat envia uma requisição POST para a URL configurada por você. O payload é enviado em formato JSON contendo os dados do evento.

1. Evento acontece

Um evento é disparado dentro do JuriChat.

2. Webhook enviado

O JuriChat envia uma requisição POST para sua URL.

3. Seu sistema processa

Sua aplicação recebe e processa o payload enviado.

4. Confirmação

Sua API responde com qualquer status HTTP 2xx.

Requisitos da sua aplicação

Para garantir o funcionamento correto dos webhooks:

HTTPS

Utilize HTTPS para receber eventos com segurança.

Resposta rápida

Seu endpoint deve responder em até 30 segundos.

Status 2xx

Retorne qualquer status HTTP 2xx para confirmar o recebimento.

JSON

Sua aplicação deve aceitar payloads JSON.

Cabeçalhos enviados

Cada webhook enviado pelo JuriChat contém os seguintes cabeçalhos:

Header	Descrição
`X-JuriChat-Event`	Nome do evento
`X-JuriChat-Signature`	Assinatura HMAC-SHA256 do payload
`X-JuriChat-Delivery`	Identificador único da entrega
`X-JuriChat-Timestamp`	Data e hora da tentativa em formato ISO 8601 UTC
`Content-Type`	Sempre `application/json`

Assinatura

Todos os webhooks são assinados utilizando HMAC-SHA256 para permitir a verificação de autenticidade da requisição. A assinatura é calculada exclusivamente sobre o body bruto (raw body) da requisição, utilizando o segredo do webhook. O valor enviado no header X-JuriChat-Signature possui o formato:

sha256=<hash_hexadecimal>

Importante:

Apenas o body bruto participa do cálculo da assinatura.
Headers como X-JuriChat-Timestamp e X-JuriChat-Delivery não fazem parte da assinatura.
Alterações no JSON (espaços, formatação ou reserialização) podem invalidar a verificação.

Timestamp

O header X-JuriChat-Timestamp informa o momento em que aquela tentativa de entrega foi realizada. O valor é enviado no padrão ISO 8601 em UTC. Exemplo:

2026-08-06T14:36:00.123Z

Proteção contra replay

O JuriChat não define uma janela oficial de validade para o timestamp enviado. Caso sua aplicação deseje evitar processamentos duplicados, recomendamos utilizar o valor do header X-JuriChat-Delivery como chave de idempotência, garantindo que cada entrega seja processada apenas uma vez.

Campos do evento

Todos os eventos seguem a estrutura abaixo:

{
  "event": "chat.message.received",
  "timestamp": "2026-08-06T14:36:00.123Z",
  "data": {}
}

Cada tipo de evento possui seu próprio objeto data. Importante: Os payloads não incluem:

Informações do canal de origem;
Lista de anexos;
Objetos completos e aninhados de conversa;
Objetos completos e aninhados de contato.

Os eventos enviam apenas os campos necessários para identificar e processar a ocorrência.

Exemplo de payload

{
  "event": "chat.message.received",
  "timestamp": "2026-08-06T14:36:00.123Z",
  "data": {
    "messageId": "...",
    "conversationId": "...",
    "personId": "...",
    "personName": "Maria Silva",
    "personPhone": "+5511999990000",
    "inboxId": "...",
    "inboxName": "Atendimento Principal",
    "content": "Olá, preciso de ajuda",
    "type": "text"
  }
}

Política de retry

Caso sua aplicação não responda com um status HTTP 2xx, o JuriChat tentará reenviar automaticamente o webhook. São realizadas até 3 tentativas no total (incluindo a tentativa inicial), utilizando o backoff configurado pelo sistema.

Após a última tentativa, a entrega será marcada como falha e não haverá novos reenvios automáticos.

​Como funciona

1. Evento acontece

2. Webhook enviado

3. Seu sistema processa

4. Confirmação

​Requisitos da sua aplicação

HTTPS

Resposta rápida

Status 2xx

JSON

​Cabeçalhos enviados

​Assinatura

​Timestamp

​Proteção contra replay

​Campos do evento

​Exemplo de payload

​Política de retry

Como funciona

Requisitos da sua aplicação

Cabeçalhos enviados

Assinatura

Timestamp

Proteção contra replay

Campos do evento

Exemplo de payload

Política de retry