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

# Webhooks (gestão via API)

> Criar, listar, atualizar e remover webhooks da conta programaticamente.

Esta página cobre **a gestão dos webhooks** via API — como cadastrar URLs receptoras
e gerenciar suas configurações. Para entender os **eventos** que esses webhooks
recebem (payload, retry, validação de assinatura), veja [Webhooks](/essentials/webhooks).

**Base:** `https://chat.lfautomatiza.com/api/v1/accounts/{account_id}`

***

## Listar webhooks

```http theme={null}
GET /webhooks
```

### Requisição

```bash cURL theme={null}
curl https://chat.lfautomatiza.com/api/v1/accounts/1/webhooks \
  -H "api_access_token: $TOKEN"
```

### Resposta `200`

```json theme={null}
{
  "payload": [
    {
      "id": 1,
      "url": "https://meu-n8n.com/webhook/lf-events",
      "account_id": 1,
      "subscriptions": ["conversation_created", "message_created"],
      "created_at": "2026-04-12T10:00:00Z"
    },
    {
      "id": 2,
      "url": "https://outro-servico.com/webhooks",
      "subscriptions": ["kanban.item.stage_changed", "kanban.item.status_changed"],
      "created_at": "2026-04-15T14:30:00Z"
    }
  ]
}
```

***

## Criar webhook

```http theme={null}
POST /webhooks
```

<ParamField body="url" type="string" required>HTTPS, público, retorna 200 em menos de 5s</ParamField>
<ParamField body="subscriptions" type="array" required>Lista de eventos que esse webhook recebe</ParamField>

### Eventos disponíveis pra subscription

#### Conversas

* `conversation_created`
* `conversation_status_changed`
* `conversation_updated`
* `conversation_resolved`
* `conversation_typing_on`
* `conversation_typing_off`

#### Mensagens

* `message_created`
* `message_updated`

#### Contatos

* `contact_created`
* `contact_updated`

#### Widget

* `webwidget_triggered`

#### Kanban

* `kanban.item.created`
* `kanban.item.updated`
* `kanban.item.stage_changed`
* `kanban.item.status_changed`

### Requisição

```bash cURL theme={null}
curl -X POST https://chat.lfautomatiza.com/api/v1/accounts/1/webhooks \
  -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meu-n8n.com/webhook/lf-events",
    "subscriptions": [
      "conversation_created",
      "message_created",
      "conversation_status_changed"
    ]
  }'
```

### Resposta `201`

```json theme={null}
{
  "id": 3,
  "url": "https://meu-n8n.com/webhook/lf-events",
  "subscriptions": [
    "conversation_created",
    "message_created",
    "conversation_status_changed"
  ],
  "account_id": 1,
  "created_at": "2026-05-19T00:30:00Z"
}
```

***

## Atualizar webhook

```http theme={null}
PATCH /webhooks/{id}
PUT /webhooks/{id}
```

<ParamField path="id" type="integer" required>ID do webhook</ParamField>
<ParamField body="url" type="string">Nova URL</ParamField>
<ParamField body="subscriptions" type="array">Nova lista de eventos (substitui completamente a anterior)</ParamField>

### Requisição

```bash cURL theme={null}
curl -X PATCH https://chat.lfautomatiza.com/api/v1/accounts/1/webhooks/3 \
  -H "api_access_token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": ["message_created"]
  }'
```

### Resposta `200`

```json theme={null}
{
  "id": 3,
  "url": "https://meu-n8n.com/webhook/lf-events",
  "subscriptions": ["message_created"],
  "updated_at": "2026-05-19T00:45:00Z"
}
```

***

## Excluir webhook

```http theme={null}
DELETE /webhooks/{id}
```

<ParamField path="id" type="integer" required>ID do webhook</ParamField>

### Requisição

```bash cURL theme={null}
curl -X DELETE https://chat.lfautomatiza.com/api/v1/accounts/1/webhooks/3 \
  -H "api_access_token: $TOKEN"
```

### Resposta `204`

Sem corpo.

***

## Webhook secret (validação de assinatura)

Quando configurar `secret` via UI da plataforma, todo POST vem com header de
assinatura HMAC-SHA256. Veja [Webhooks → Verificação de assinatura](/essentials/webhooks)
para o código de validação em Node.js, Python, etc.

***

## Comportamento de retry

Se sua URL não retornar `2xx` em até 5s, há retentativas automáticas:

| Tentativa     | Espera       |
| ------------- | ------------ |
| 1ª retry      | 30s depois   |
| 2ª retry      | 2min depois  |
| 3ª retry      | 10min depois |
| Após 3 falhas | Descartado   |

<Warning>
  Não há fila persistente — você é responsável por absorver o evento com sucesso
  na sua URL. Eventos descartados não voltam.
</Warning>

***

## Boas práticas

<AccordionGroup>
  <Accordion title="URL receptora deve ser idempotente">
    Em caso de retry, sua URL pode receber o mesmo evento mais de uma vez. Use o
    `id` do payload pra deduplicar e evitar processamento duplicado.
  </Accordion>

  <Accordion title="Responda rápido — processe depois">
    Sua URL deve só receber, validar assinatura e empilhar em fila própria
    (SQS, Bull, Redis Stream). Processar de forma síncrona dentro do webhook
    é o caminho mais rápido pra perder evento por timeout.
  </Accordion>

  <Accordion title="Separe webhooks por uso">
    Em vez de 1 webhook subscrito a 15 eventos, considere 3 webhooks por área
    (vendas, suporte, financeiro). Mais fácil de monitorar e desligar parcialmente
    em caso de problema.
  </Accordion>

  <Accordion title="Sempre HTTPS">
    URLs HTTP são rejeitadas na criação. Use HTTPS válido (Let's Encrypt grátis serve).
  </Accordion>
</AccordionGroup>

***

## Códigos de resposta

| Código                     | Quando acontece                                                   |
| -------------------------- | ----------------------------------------------------------------- |
| `200 OK`                   | Listagem / atualização                                            |
| `201 Created`              | Webhook criado                                                    |
| `204 No Content`           | Removido                                                          |
| `403 Forbidden`            | Não é administrador                                               |
| `422 Unprocessable Entity` | URL inválida (não-HTTPS, malformada) ou subscription desconhecida |