> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jurichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

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.

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

***

## 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.

<CardGroup cols={2}>
  <Card title="1. Evento acontece" icon="bolt">
    Um evento é disparado dentro do JuriChat.
  </Card>

  <Card title="2. Webhook enviado" icon="paper-plane">
    O JuriChat envia uma requisição POST para sua URL.
  </Card>

  <Card title="3. Seu sistema processa" icon="server">
    Sua aplicação recebe e processa o payload enviado.
  </Card>

  <Card title="4. Confirmação" icon="circle-check">
    Sua API responde com qualquer status HTTP 2xx.
  </Card>
</CardGroup>

***

## Requisitos da sua aplicação

Para garantir o funcionamento correto dos webhooks:

<CardGroup cols={2}>
  <Card title="HTTPS" icon="lock">
    Utilize HTTPS para receber eventos com segurança.
  </Card>

  <Card title="Resposta rápida" icon="bolt">
    Seu endpoint deve responder em até 30 segundos.
  </Card>

  <Card title="Status 2xx" icon="circle-check">
    Retorne qualquer status HTTP 2xx para confirmar o recebimento.
  </Card>

  <Card title="JSON" icon="brackets-curly">
    Sua aplicação deve aceitar payloads JSON.
  </Card>
</CardGroup>

***

## 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:

```text theme={null}
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:

```text theme={null}
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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

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