Webhooks

Os webhooks do Lifty são chamadas POST que fazemos para uma API que você disponibiliza, servindo como um proxy do servidor da Meta. Funcionamos como um espelho do que recebemos, retransmitindo todas as notificações em tempo real.

🔄 O que são Webhooks?

Webhooks são URLs que recebem dados automaticamente quando eventos específicos ocorrem. No caso do Lifty, funcionamos como um proxy inteligente que:

Recebe notificações do servidor da Meta (WhatsApp Business API)
Processa e enriquece os dados quando necessário
Retransmite para sua API através de chamadas POST
Garante entrega confiável e retry automático

Como Funciona

Meta envia notificação para o Lifty
Lifty processa e enriquece os dados
Lifty faz POST para sua API
Sua API responde com status 200
Lifty confirma recebimento para a Meta

📡 Status de Mensagens Disponíveis

O Lifty envia webhooks para todos os status de mensagem definidos no enum MessageStatus:

Status de Mensagem

NEW - Nova mensagem criada/recebida
QUEUED - Mensagem na fila para envio
SENT - Mensagem enviada com sucesso
PENDING - Mensagem pendente de confirmação
FAILED - Falha no envio da mensagem
DELIVERED - Mensagem entregue ao destinatário
READ - Mensagem lida pelo destinatário
UNDELIVERABLE - Mensagem não pode ser entregue
DELETE - Mensagem deletada

Fluxo Típico de Status

NEW → Mensagem recebida do usuário
QUEUED → Mensagem do bot na fila
SENT → Mensagem enviada pelo WhatsApp
DELIVERED → Mensagem entregue ao usuário
READ → Mensagem lida pelo usuário

Status de Erro

FAILED → Erro no envio (ex: número inválido)
UNDELIVERABLE → Mensagem não pode ser entregue
DELETE → Mensagem removida

⚙️ Configurando Webhooks

1. Criar seu Webhook

Primeiro, você precisa criar seu próprio endpoint webhook. Aqui estão exemplos de como fazer isso:

Node.js/Express

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const message = req.body;
  
  // Log simples do que chegou
  console.log('=== Webhook Recebido ===');
  console.log('ID:', message.id);
  console.log('Status:', message.status);
  console.log('Participante:', message.participant);
  console.log('Conteúdo:', message.content);
  console.log('Conversa:', message.conversationId);
  console.log('Timestamp:', message.timeStamp);
  console.log('========================');
  
  // IMPORTANTE: Sempre retorne 200
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server rodando na porta 3000');
});

Python/Flask

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    message = request.json
    
    # Log simples do que chegou
    print('=== Webhook Recebido ===')
    print('ID:', message.get('id'))
    print('Status:', message.get('status'))
    print('Participante:', message.get('participant'))
    print('Conteúdo:', message.get('content'))
    print('Conversa:', message.get('conversationId'))
    print('Timestamp:', message.get('timeStamp'))
    print('========================')
    
    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(debug=True, port=3000)

2. Configurar no Lifty

Após criar e deployar seu webhook, entre em contato conosco com:

URL do webhook: https://suaempresa.com/webhook
API_KEY: Chave secreta para validar assinaturas

Exemplo de configuração:

URL: https://minhaempresa.com/api/webhook
api_key: minha_chave_secreta_123

3. Testar Webhook

Após a configuração, você pode testar enviando uma mensagem pelo WhatsApp. Seu webhook deve receber os payloads com os status das mensagens.

📦 Estrutura do Payload

Todos os webhooks seguem a estrutura json abaixo:

{
  "id": "653364084525498_5585989090412_1754331016874",
  "messageId": "wamid.HBgMNTU4NTg5MDkwNDEyFQIAEhggM0FCOTkyNUI1QkZFNjVCMzc1RUY2OEVEODM5NjQ2RUYA",
  "replyMessageId": null,
  "replyMessageContent": null,
  "messageContextId": null,
  "conversationId": "653364084525498_5585989090412",
  "threadId": null,
  "type": "text",
  "content": "Olá! Como posso ajudar?",
  "language": "pt-BR",
  "participant": "Marciana",
  "participantRole": "END_USER",
  "timeStamp": "Mon Aug 04 15:10:16 GMT-03:00 2025",
  "status": "SENT",
  "reaction": null,
  "channelDetails": [
    {
      "messageId": "wamid.HBgMNTU4NTg5MDkwNDEyFQIAEhggM0FCOTkyNUI1QkZFNjVCMzc1RUY2OEVEODM5NjQ2RUYA",
      "messageStatus": "SENT"
    }
  ],
  "channel": "WHATSAPP",
  "errorMessage": null
}

Campos do Payload

Campo	Tipo	Descrição
`id`	String	ID único da mensagem no Lifty
`messageId`	String	ID da mensagem no canal (WhatsApp)
`replyMessageId`	String	ID da mensagem respondida (se for resposta)
`replyMessageContent`	String	Conteúdo da mensagem respondida
`messageContextId`	String	ID do contexto da mensagem
`conversationId`	String	ID da conversa no Lifty
`threadId`	String	ID do thread da conversa
`type`	String	Tipo da mensagem (text, image, audio, etc.)
`content`	String	Conteúdo da mensagem
`language`	String	Idioma da mensagem
`participant`	String	Nome ou número do participante
`participantRole`	String	Papel do participante (END_USER, AGENT, BOT)
`timeStamp`	String	Timestamp da mensagem
`status`	String	Status da mensagem (NEW, QUEUED, SENT, PENDING, FAILED, DELIVERED, READ, UNDELIVERABLE, DELETE)
`reaction`	String	Reação à mensagem (se houver)
`channelDetails`	Array	Detalhes específicos do canal
`channel`	String	Canal da mensagem (WHATSAPP)
`errorMessage`	String	Mensagem de erro (se houver)

Status de Mensagem (MessageStatus)

Status	Código	Descrição
`NEW`	0	Nova mensagem criada
`QUEUED`	1	Mensagem na fila para envio
`SENT`	2	Mensagem enviada com sucesso
`PENDING`	3	Mensagem pendente de confirmação
`FAILED`	4	Falha no envio da mensagem
`DELIVERED`	5	Mensagem entregue ao destinatário
`READ`	6	Mensagem lida pelo destinatário
`UNDELIVERABLE`	7	Mensagem não pode ser entregue
`DELETE`	8	Mensagem deletada

Exemplo: Status SENT

{
  "id": "653364084525498_5585989090412_1754331016875",
  "messageId": "wamid.HBgMNTU4NTg5MDkwNDEyFQIAEhggM0FCOTkyNUI1QkZFNjVCMzc1RUY2OEVEODM5NjQ2RUYB",
  "replyMessageId": null,
  "replyMessageContent": null,
  "messageContextId": null,
  "conversationId": "653364084525498_5585989090412",
  "threadId": null,
  "type": "text",
  "content": "Olá! Como posso ajudar?",
  "language": "pt-BR",
  "participant": "Bot Atendente",
  "participantRole": "BOT",
  "timeStamp": "Mon Aug 04 15:10:17 GMT-03:00 2025",
  "status": "SENT",
  "reaction": null,
  "channelDetails": [
    {
      "messageId": "wamid.HBgMNTU4NTg5MDkwNDEyFQIAEhggM0FCOTkyNUI1QkZFNjVCMzc1RUY2OEVEODM5NjQ2RUYB",
      "messageStatus": "SENT"
    }
  ],
  "channel": "WHATSAPP",
  "errorMessage": null
}

Exemplo: Status FAILED

{
  "id": "496909553503461_5548936182822_1754331694164",
  "messageId": null,
  "replyMessageId": null,
  "replyMessageContent": null,
  "messageContextId": null,
  "conversationId": "496909553503461_5548936182822",
  "threadId": null,
  "type": null,
  "content": null,
  "language": null,
  "participant": null,
  "participantRole": null,
  "timeStamp": null,
  "status": "FAILED",
  "reaction": null,
  "channelDetails": null,
  "channel": null,
  "errorMessage": "Invalid phone number"
}

📋 Boas Práticas

1. Sempre retorne 200

Seu endpoint deve sempre retornar status 200 para confirmar recebimento. Caso contrário, faremos retry.

2. Processamento assíncrono

Processe webhooks de forma assíncrona para não bloquear a resposta.

3. Idempotência

Seu endpoint deve ser idempotente (pode ser chamado múltiplas vezes sem efeitos colaterais).

4. Timeout

Configure timeout adequado (recomendado: 30 segundos).

5. Logs

Mantenha logs dos webhooks recebidos para debug.

6. Retry automático

O Lifty faz retry automático em caso de falha (máximo 3 tentativas).

Este guia será atualizado conforme novas funcionalidades forem disponibilizadas na plataforma.