# Webhooks

> Cadastrar, editar, testar, trocar o segredo e ver as entregas dos webhooks.

Conceitos, regras e exemplos no guia: [Webhooks de saída e assinatura](https://docs.forsi.com.br/webhooks).

**Códigos de erro comuns aqui**: `webhook_inexistente`, `entrega_inexistente`, `webhook_desativado`, `entrega_em_andamento`, `entrega_ja_despachada`, `url_invalida`, `destino_bloqueado`, `dns_falhou`, `eventos_invalidos`, `limite_de_webhooks`, `nome_invalido`, `graca_invalida` (todos em [Erros](https://docs.forsi.com.br/erros)).

## GET /webhooks — Listar webhooks

- URL: `GET https://chat.forsi.com.br/api/v1/webhooks`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com lista de `Webhook`
- Página: https://docs.forsi.com.br/api/webhooks/listar-webhooks (Markdown: https://docs.forsi.com.br/api/webhooks/listar-webhooks.md)

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": [
    {
      "id": "506b7dac-d0bc-4954-8d45-0015588d64b5",
      "nome": "CRM",
      "url": "https://seu-sistema.com.br/webhooks/forsi",
      "eventos": ["mensagem.recebida"],
      "ativo": true,
      "segredo_dica": "…a1B2c3",
      "segredo_anterior_ate": "2026-10-04T13:05:12.481Z",
      "falhas_seguidas": 0,
      "falhando_desde": "2026-10-04T13:05:12.481Z",
      "desativado_em": "2026-10-04T13:05:12.481Z",
      "motivo_desativacao": "falhas_seguidas",
      "ultima_entrega_em": "2026-10-04T13:05:12.481Z",
      "ultimo_status": 200,
      "criado_em": "2026-10-04T13:05:12.481Z",
      "atualizado_em": "2026-10-04T13:05:12.481Z",
      "entregas_24h": {"entregues":42,"falhas":0,"pendentes":0}
    }
  ]
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /webhooks — Criar webhook

- URL: `POST https://chat.forsi.com.br/api/v1/webhooks`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `201`, `{"dados": ...}` com `WebhookComSegredo`
- Página: https://docs.forsi.com.br/api/webhooks/criar-webhook (Markdown: https://docs.forsi.com.br/api/webhooks/criar-webhook.md)

Responde com `segredo` UMA vez: guarde para conferir a assinatura `X-Forsi-Signature`. Repetir com a mesma `Idempotency-Key` devolve o webhook sem `segredo` e sem criar outro.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `nome` | string | sim | até 60 caracteres |
| `url` | string | sim | https, porta 443, nome público (sem IP, sem rede interna). até 2000 caracteres |
| `eventos` | lista de "mensagem.recebida" \| "mensagem.enviada" \| "mensagem.status" \| "conversa.criada" \| "conversa.atribuida" \| "conversa.encerrada" \| "contato.criado" \| "negocio.criado" \| "negocio.movido" \| "negocio.ganho" \| "negocio.perdido" \| "agendamento.criado" \| "agendamento.remarcado" \| "agendamento.cancelado" \| "agendamento.confirmado" \| "membro.convidado" \| "membro.entrou" \| "membro.alterado" \| "membro.removido" | sim | mín. 1 item até 19 itens |

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{
    "nome": "CRM",
    "url": "https://seu-sistema.com.br/webhooks/forsi",
    "eventos": ["mensagem.recebida","mensagem.status"]
  }'
```

**Resposta `201` (exemplo)**

```json
{
  "dados": {
    "id": "506b7dac-d0bc-4954-8d45-0015588d64b5",
    "nome": "CRM",
    "url": "https://seu-sistema.com.br/webhooks/forsi",
    "eventos": ["mensagem.recebida"],
    "ativo": true,
    "segredo_dica": "…a1B2c3",
    "segredo_anterior_ate": "2026-10-04T13:05:12.481Z",
    "falhas_seguidas": 0,
    "falhando_desde": "2026-10-04T13:05:12.481Z",
    "desativado_em": "2026-10-04T13:05:12.481Z",
    "motivo_desativacao": "falhas_seguidas",
    "ultima_entrega_em": "2026-10-04T13:05:12.481Z",
    "ultimo_status": 200,
    "criado_em": "2026-10-04T13:05:12.481Z",
    "atualizado_em": "2026-10-04T13:05:12.481Z",
    "entregas_24h": {"entregues":42,"falhas":0,"pendentes":0},
    "segredo": "whsec_EXAMPLE"
  }
}
```

**Erros**: `401`, `403`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /webhooks/{id} — Ver um webhook

- URL: `GET https://chat.forsi.com.br/api/v1/webhooks/{id}`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Webhook`
- Página: https://docs.forsi.com.br/api/webhooks/ver-webhook (Markdown: https://docs.forsi.com.br/api/webhooks/ver-webhook.md)

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/webhooks/506b7dac-d0bc-4954-8d45-0015588d64b5" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": {
    "id": "506b7dac-d0bc-4954-8d45-0015588d64b5",
    "nome": "CRM",
    "url": "https://seu-sistema.com.br/webhooks/forsi",
    "eventos": ["mensagem.recebida"],
    "ativo": true,
    "segredo_dica": "…a1B2c3",
    "segredo_anterior_ate": "2026-10-04T13:05:12.481Z",
    "falhas_seguidas": 0,
    "falhando_desde": "2026-10-04T13:05:12.481Z",
    "desativado_em": "2026-10-04T13:05:12.481Z",
    "motivo_desativacao": "falhas_seguidas",
    "ultima_entrega_em": "2026-10-04T13:05:12.481Z",
    "ultimo_status": 200,
    "criado_em": "2026-10-04T13:05:12.481Z",
    "atualizado_em": "2026-10-04T13:05:12.481Z",
    "entregas_24h": {"entregues":42,"falhas":0,"pendentes":0}
  }
}
```

**Erros**: `401`, `403`, `404`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## PATCH /webhooks/{id} — Atualizar webhook

- URL: `PATCH https://chat.forsi.com.br/api/v1/webhooks/{id}`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Webhook`
- Página: https://docs.forsi.com.br/api/webhooks/atualizar-webhook (Markdown: https://docs.forsi.com.br/api/webhooks/atualizar-webhook.md)

Mude nome, URL, eventos, ou pause/reative.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `nome` | string | não | até 60 caracteres |
| `url` | string | não | até 2000 caracteres |
| `eventos` | lista de "mensagem.recebida" \| "mensagem.enviada" \| "mensagem.status" \| "conversa.criada" \| "conversa.atribuida" \| "conversa.encerrada" \| "contato.criado" \| "negocio.criado" \| "negocio.movido" \| "negocio.ganho" \| "negocio.perdido" \| "agendamento.criado" \| "agendamento.remarcado" \| "agendamento.cancelado" \| "agendamento.confirmado" \| "membro.convidado" \| "membro.entrou" \| "membro.alterado" \| "membro.removido" | não | mín. 1 item até 19 itens |
| `ativo` | boolean | não | false pausa; true reativa (zera as falhas). |

**Exemplo (curl)**

```bash
curl -X PATCH "https://chat.forsi.com.br/api/v1/webhooks/506b7dac-d0bc-4954-8d45-0015588d64b5" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"ativo":true}'
```

**Resposta `200`**: mesmo formato do exemplo de `Webhook` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## DELETE /webhooks/{id} — Apagar webhook

- URL: `DELETE https://chat.forsi.com.br/api/v1/webhooks/{id}`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Apagado`
- Página: https://docs.forsi.com.br/api/webhooks/apagar-webhook (Markdown: https://docs.forsi.com.br/api/webhooks/apagar-webhook.md)

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl -X DELETE "https://chat.forsi.com.br/api/v1/webhooks/506b7dac-d0bc-4954-8d45-0015588d64b5" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{"dados":{"apagado":false,"conversas_apagadas":1}}
```

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /webhooks/{id}/rotacionar — Trocar o segredo

- URL: `POST https://chat.forsi.com.br/api/v1/webhooks/{id}/rotacionar`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `200`, `{"dados": ...}` com `WebhookComSegredo`
- Página: https://docs.forsi.com.br/api/webhooks/rotacionar-webhook (Markdown: https://docs.forsi.com.br/api/webhooks/rotacionar-webhook.md)

Gera um segredo novo (mostrado uma vez; repetir com a mesma `Idempotency-Key` não gira de novo nem repete o segredo). Durante a graça as entregas levam as duas assinaturas.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON, opcional)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `horas` | integer | não | Quanto tempo o segredo antigo ainda assina junto (0 a 168, padrão 24). |

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/webhooks/506b7dac-d0bc-4954-8d45-0015588d64b5/rotacionar" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{"horas":24}'
```

**Resposta `200`**: mesmo formato do exemplo de `WebhookComSegredo` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /webhooks/{id}/testar — Mandar um evento de teste

- URL: `POST https://chat.forsi.com.br/api/v1/webhooks/{id}/testar`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `202`, `{"dados": ...}` com `TesteAceito`
- Página: https://docs.forsi.com.br/api/webhooks/testar-webhook (Markdown: https://docs.forsi.com.br/api/webhooks/testar-webhook.md)

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON, opcional)**

Sem campos: mande `{}` ou nenhum corpo.

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/webhooks/506b7dac-d0bc-4954-8d45-0015588d64b5/testar" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{}'
```

**Resposta `202` (exemplo)**

```json
{"dados":{"entrega_id":"4a989b41-b6e1-414a-ba98-158a58f4195d"}}
```

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /webhooks/{id}/entregas — Histórico de entregas

- URL: `GET https://chat.forsi.com.br/api/v1/webhooks/{id}/entregas`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com lista de `Entrega`
- Página: https://docs.forsi.com.br/api/webhooks/listar-entregas (Markdown: https://docs.forsi.com.br/api/webhooks/listar-entregas.md)

50 por página, da mais nova para a mais antiga, com o corpo enviado e a resposta.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `estado` | "pendente" \| "falhou" \| "entregue" \| "morta" \| "cancelada" | não |  |
| `antes` | uuid | não | Id da última entrega vista (página seguinte). |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/webhooks/506b7dac-d0bc-4954-8d45-0015588d64b5/entregas?estado=falhou" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": [
    {
      "id": "4a989b41-b6e1-414a-ba98-158a58f4195d",
      "webhook_id": "506b7dac-d0bc-4954-8d45-0015588d64b5",
      "evento": "mensagem.recebida",
      "evento_id": "5e458e2a-2f89-4c56-8f5e-f6bfa9ef0a35",
      "estado": "pendente",
      "tentativas": 1,
      "status_http": 200,
      "resposta": "ok",
      "erro": "Connection timed out",
      "duracao_ms": 182,
      "criado_em": "2026-10-04T13:05:12.481Z",
      "ultima_tentativa_em": "2026-10-04T13:05:12.481Z",
      "proxima_em": "2026-10-04T13:05:12.481Z",
      "entregue_em": "2026-10-04T13:05:12.481Z",
      "payload": {
        "id": "5e458e2a-2f89-4c56-8f5e-f6bfa9ef0a35",
        "evento": "mensagem.recebida",
        "criado_em": "2026-10-04T13:05:12.481Z",
        "organizacao_id": "dddecb67-6b55-43da-94f6-18c8d6680571",
        "dados": {
          "mensagem": {
            "id": "4e8cb5d0-2d89-4fc2-93bb-c8e5e17d4629",
            "conversa_id": "495a7cae-128c-4b66-adbc-807b3959c129",
            "direcao": "entrada",
            "tipo": "texto",
            "texto": "Oi, queria remarcar minha consulta",
            "autor_tipo": "contato",
            "criado_em": "2026-10-04T13:05:11.902Z"
          },
          "conversa": {
            "id": "495a7cae-128c-4b66-adbc-807b3959c129",
            "estado": "aberta",
            "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
          },
          "contato": {
            "id": "08054a7f-a752-481e-9915-cf4cf944df39",
            "nome": "Maria Souza",
            "telefone": "+5531988887777"
          }
        }
      }
    }
  ]
}
```

**Erros**: `401`, `403`, `404`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /webhooks/entregas/{id}/reenviar — Reenviar uma entrega

- URL: `POST https://chat.forsi.com.br/api/v1/webhooks/entregas/{id}/reenviar`
- Acesso: escopo `webhooks:gerir` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `202`, `{"dados": ...}` com `Entrega`
- Página: https://docs.forsi.com.br/api/webhooks/reenviar-entrega (Markdown: https://docs.forsi.com.br/api/webhooks/reenviar-entrega.md)

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON, opcional)**

Sem campos: mande `{}` ou nenhum corpo.

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/webhooks/entregas/4a989b41-b6e1-414a-ba98-158a58f4195d/reenviar" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{}'
```

**Resposta `202` (exemplo)**

```json
{
  "dados": {
    "id": "4a989b41-b6e1-414a-ba98-158a58f4195d",
    "webhook_id": "506b7dac-d0bc-4954-8d45-0015588d64b5",
    "evento": "mensagem.recebida",
    "evento_id": "5e458e2a-2f89-4c56-8f5e-f6bfa9ef0a35",
    "estado": "pendente",
    "tentativas": 1,
    "status_http": 200,
    "resposta": "ok",
    "erro": "Connection timed out",
    "duracao_ms": 182,
    "criado_em": "2026-10-04T13:05:12.481Z",
    "ultima_tentativa_em": "2026-10-04T13:05:12.481Z",
    "proxima_em": "2026-10-04T13:05:12.481Z",
    "entregue_em": "2026-10-04T13:05:12.481Z",
    "payload": {
      "id": "5e458e2a-2f89-4c56-8f5e-f6bfa9ef0a35",
      "evento": "mensagem.recebida",
      "criado_em": "2026-10-04T13:05:12.481Z",
      "organizacao_id": "dddecb67-6b55-43da-94f6-18c8d6680571",
      "dados": {
        "mensagem": {
          "id": "4e8cb5d0-2d89-4fc2-93bb-c8e5e17d4629",
          "conversa_id": "495a7cae-128c-4b66-adbc-807b3959c129",
          "direcao": "entrada",
          "tipo": "texto",
          "texto": "Oi, queria remarcar minha consulta",
          "autor_tipo": "contato",
          "criado_em": "2026-10-04T13:05:11.902Z"
        },
        "conversa": {
          "id": "495a7cae-128c-4b66-adbc-807b3959c129",
          "estado": "aberta",
          "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445"
        },
        "contato": {
          "id": "08054a7f-a752-481e-9915-cf4cf944df39",
          "nome": "Maria Souza",
          "telefone": "+5531988887777"
        }
      }
    }
  }
}
```

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## Objetos das respostas

Campos de cada objeto devolvido em `dados`. Campos novos podem aparecer: ignore os que não conhecer.

### Webhook

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `nome` | string | não |  |
| `url` | string | não |  |
| `eventos` | lista de "mensagem.recebida" \| "mensagem.enviada" \| "mensagem.status" \| "conversa.criada" \| "conversa.atribuida" \| "conversa.encerrada" \| "contato.criado" \| "negocio.criado" \| "negocio.movido" \| "negocio.ganho" \| "negocio.perdido" \| "agendamento.criado" \| "agendamento.remarcado" \| "agendamento.cancelado" \| "agendamento.confirmado" \| "membro.convidado" \| "membro.entrou" \| "membro.alterado" \| "membro.removido" | não |  |
| `ativo` | boolean | não |  |
| `segredo_dica` | string | não | ex.: …a1B2c3 |
| `segredo_anterior_ate` | data e hora ISO 8601 ou null | não |  |
| `falhas_seguidas` | integer | não |  |
| `falhando_desde` | data e hora ISO 8601 ou null | não |  |
| `desativado_em` | data e hora ISO 8601 ou null | não |  |
| `motivo_desativacao` | string ou null | não |  |
| `ultima_entrega_em` | data e hora ISO 8601 ou null | não |  |
| `ultimo_status` | integer ou null | não |  |
| `criado_em` | data e hora ISO 8601 | não |  |
| `atualizado_em` | data e hora ISO 8601 | não |  |
| `entregas_24h` | object | não |  |
| `entregas_24h.entregues` | integer | não |  |
| `entregas_24h.falhas` | integer | não |  |
| `entregas_24h.pendentes` | integer | não |  |

### Apagado

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `apagado` | boolean | não |  |
| `conversas_apagadas` | integer | não |  |

### TesteAceito

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `entrega_id` | uuid | não |  |

### Entrega

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `webhook_id` | uuid | não |  |
| `evento` | string | não |  |
| `evento_id` | uuid | não |  |
| `estado` | "pendente" \| "falhou" \| "entregue" \| "morta" \| "cancelada" | não |  |
| `tentativas` | integer | não |  |
| `status_http` | integer ou null | não |  |
| `resposta` | string ou null | não |  |
| `erro` | string ou null | não |  |
| `duracao_ms` | integer ou null | não |  |
| `criado_em` | data e hora ISO 8601 | não |  |
| `ultima_tentativa_em` | data e hora ISO 8601 ou null | não |  |
| `proxima_em` | data e hora ISO 8601 ou null | não |  |
| `entregue_em` | data e hora ISO 8601 ou null | não |  |
| `payload` | Evento | não |  |

---

Página: https://docs.forsi.com.br/api/webhooks · Índice: https://docs.forsi.com.br/llms.txt · Tudo num arquivo: https://docs.forsi.com.br/llms-full.txt