Configurar Webhooks

Configure webhooks para receber notificações em tempo real sobre mensagens, atualizações de status de entrega e eventos de campanhas.

conversation.closed — Conversa encerrada

Um evento ocorre (ex: mensagem recebida)

SendSeven envia HTTP POST para o seu URL

Se não houver 200, tentamos novamente com backoff exponencial

Eventos: Selecione quais eventos deseja receber

ID único do evento (use para deduplicação)

String do tipo de evento (ex.: message.received)

Timestamp ISO 8601 de quando o evento ocorreu

Payload específico do evento (varia por tipo de evento)

O array attachments só está presente quando a mensagem inclui mídia. Cada anexo inclui um id único, content_type, file_size e duas URLs de download. Tipos suportados: imagem, vídeo, áudio, documento, sticker.

url - Endpoint estável da API. Requer autenticação (API key ou token de sessão). Nunca expira.

signed_url - URL GCS pré-assinada. Não requer autenticação. Expira após 24 horas.

Se o download de mídia da plataforma falhar, os dados brutos da plataforma são passados com um marcador "source": "platform" em vez dos campos enriquecidos. Tipos que não são arquivo (localização, contatos, reações) não são afetados.

Cada evento que inclui um objeto de contato também contém um array contact_methods[] listando todos os identificadores do contato (o principal primeiro). Os campos phone e email de nível superior são mantidos para compatibilidade retroativa.

Seleções de resposta rápida e de lista chegam como message_type "button". A legenda está em "text" e um objeto "meta.button" estruturado contém o id e o payload, permitindo rotear a seleção sem analisar o texto.

Mostrar exemplo com clique em botão (resposta rápida / lista)

Identificador estável do botão conforme definido no envio da mensagem.

Payload retornado pelo canal (corresponde ao id para respostas rápidas).

Legenda legível que o usuário viu e tocou.

Mensagens de saída que incluem anexos de arquivo contêm o mesmo schema enriquecido de anexo (id, url, signed_url, content_type, file_size) das mensagens de entrada.

O campo error está no nível de dados (não dentro de message.meta). Os objetos completos de conversa e contato também são incluídos.

Eventos de atualização de status (delivered, read) usam um objeto de conversa mais simples sem bot_session_id ou campos de timestamp last_*_at. O objeto contact_method não é incluído.

Objetos de conversa de email incluem campos adicionais: email_integration_id e email_thread_id para contexto de threading.

O evento reopened inclui menos campos de conversa do que outros eventos de conversa (sem bot_session_id, timestamps last_*_at ou subject).

contact.updated e contact.deleted usam a mesma estrutura. O campo type do evento distingue entre eles.

Obtenha o corpo bruto da requisição (antes de fazer parse do JSON)

Calcule HMAC-SHA256 usando o seu segredo do webhook

Compare com o cabeçalho X-SendSeven-Signature

Use comparação timing-safe para prevenir ataques de timing

O seu URL é publicamente acessível (não localhost)

O seu certificado SSL é válido (não auto-assinado)

Não há firewall a bloquear os IPs da SendSeven

Usando JSON parsed em vez do corpo bruto

Segredo do webhook errado (copie novamente das configurações)

Middleware a modificar o corpo da requisição

Problemas de codificação (garanta UTF-8)

Guarde o ID do evento e verifique duplicados antes de processar

Torne os seus handlers de eventos idempotentes

Responda com 200 o mais rápido possível (processe de forma assíncrona)

Webhooks são callbacks HTTP que o SendSeven usa para enviar eventos em tempo real para a sua aplicação. Em vez de consultar a REST API periodicamente, seu endpoint recebe notificações instantâneas quando algo importante acontece - uma mensagem chega, uma conversa é encerrada, um contato é criado ou o status de entrega muda. Cada requisição de webhook é assinada com HMAC para segurança e automaticamente reenviada em caso de falha com backoff exponencial, garantindo que nenhum evento seja perdido.

Uma conta SendSeven com pelo menos um canal conectado

Um endpoint HTTPS público que possa receber requisições HTTP POST

Um certificado SSL válido (Let's Encrypt funciona perfeitamente)

Página de Webhooks do painel SendSeven com o botão Adicionar Endpoint destacado

Diálogo Adicionar Endpoint com campo de URL HTTPS e inscrições de eventos no SendSeven

Eventos: Selecione quais eventos receber

Cabeçalho Authorization (opcional): Cabeçalho de autenticação personalizado enviado em cada entrega

Através da API também pode configurar: retry_strategy (exponential/linear/none), max_retries (predefinição 8, máx. 15) e timeout_seconds (predefinição 30, intervalo 5–60)

Popup Webhook Criado com Sucesso exibindo a chave secreta com botão Copiar

Página de detalhes do webhook mostrando URL do endpoint, eventos inscritos, histórico de entregas e status de saúde no SendSeven

Automaticamente ao criar um webhook pelo painel

Automaticamente ao criar um webhook pela API (POST /api/v1/webhook-endpoints)

Automaticamente quando a URL do webhook é atualizada

Sob demanda via o endpoint de verificação (POST /api/v1/webhook-endpoints/{id}/verify)

1. Criar um endpoint de webhook
2. Registar o webhook no SendSeven
3. Selecionar os tipos de eventos a receber
4. Gerir o desafio de verificação do webhook
5. Verificar a assinatura do webhook
6. Gerir os eventos recebidos
7. Testar com eventos de exemplo