Webhooks (gestão via API)

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. Base: https://chat.lfautomatiza.com/api/v1/accounts/{account_id}

Listar webhooks

GET /webhooks

Requisição

cURL

curl https://chat.lfautomatiza.com/api/v1/accounts/1/webhooks \
  -H "api_access_token: $TOKEN"

Resposta `200`

{
  "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

POST /webhooks

url

string

required

HTTPS, público, retorna 200 em menos de 5s

subscriptions

array

required

Lista de eventos que esse webhook recebe

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

webwidget_triggered

Kanban

kanban.item.created
kanban.item.updated
kanban.item.stage_changed
kanban.item.status_changed

Requisição

cURL

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`

{
  "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

PATCH /webhooks/{id}
PUT /webhooks/{id}

integer

required

ID do webhook

url

string

Nova URL

subscriptions

array

Nova lista de eventos (substitui completamente a anterior)

Requisição

cURL

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`

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

Excluir webhook

DELETE /webhooks/{id}

integer

required

ID do webhook

Requisição

cURL

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

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

Boas práticas

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.

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.

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.

Sempre HTTPS

URLs HTTP são rejeitadas na criação. Use HTTPS válido (Let’s Encrypt grátis serve).

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

Visão geral

Conversas e mensagens

Organização

Operação

Kanban

Webhooks (gestão via API)

Listar webhooks

Requisição

Resposta `200`

Criar webhook

Eventos disponíveis pra subscription

Conversas

Mensagens

Contatos

Widget

Kanban

Requisição

Resposta `201`

Atualizar webhook

Requisição

Resposta `200`

Excluir webhook

Requisição

Resposta `204`

Webhook secret (validação de assinatura)

Comportamento de retry

Boas práticas

Códigos de resposta

​Listar webhooks

​Requisição

​Resposta 200

​Criar webhook

​Eventos disponíveis pra subscription

​Conversas

​Mensagens

​Contatos

​Widget

​Kanban

​Requisição

​Resposta 201

​Atualizar webhook

​Requisição

​Resposta 200

​Excluir webhook

​Requisição

​Resposta 204

​Webhook secret (validação de assinatura)

​Comportamento de retry

​Boas práticas

​Códigos de resposta

Listar webhooks

Requisição

Resposta `200`

Criar webhook

Eventos disponíveis pra subscription

Conversas

Mensagens

Contatos

Widget

Kanban

Requisição

Resposta `201`

Atualizar webhook

Requisição

Resposta `200`

Excluir webhook

Requisição

Resposta `204`

Webhook secret (validação de assinatura)

Comportamento de retry

Boas práticas

Códigos de resposta