Configurar Webhooks

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

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 unico do evento (use para deduplicacao)

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

Timestamp ISO 8601 de quando o evento ocorreu

Payload especifico do evento (varia por tipo de evento)

O array attachments so esta presente quando a mensagem inclui midia. Cada anexo inclui um id unico, content_type, file_size e duas URLs de download. Tipos suportados: imagem, video, audio, documento, sticker.

url - Endpoint estavel da API. Requer autenticacao (API key ou token de sessao). Nunca expira.

signed_url - URL GCS pre-assinada. Nao requer autenticacao. Expira apos 24 horas.

Se o download de midia da plataforma falhar, os dados brutos da plataforma sao passados com um marcador "source": "platform" em vez dos campos enriquecidos. Tipos que nao sao arquivo (localizacao, contatos, reacoes) nao sao afetados.

Cada evento que inclui um objeto de contato tambem contem um array contact_methods[] listando todos os identificadores do contato (o principal primeiro). Os campos phone e email de nivel superior sao mantidos para compatibilidade retroativa.

Selecoes de resposta rapida e de lista chegam como message_type "button". A legenda esta em "text" e um objeto "meta.button" estruturado contem o id e o payload, permitindo rotear a selecao sem analisar o texto.

Mostrar exemplo com clique em botao (resposta rapida / lista)

Identificador estavel do botao conforme definido no envio da mensagem.

Payload retornado pelo canal (corresponde ao id para respostas rapidas).

Legenda legivel que o usuario viu e tocou.

Mensagens de saida que incluem anexos de arquivo contem o mesmo schema enriquecido de anexo (id, url, signed_url, content_type, file_size) das mensagens de entrada.

O campo error esta no nivel de dados (nao dentro de message.meta). Os objetos completos de conversa e contato tambem sao incluidos.

Eventos de atualizacao 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 nao e incluido.

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 sao callbacks HTTP que o SendSeven usa para enviar eventos em tempo real para a sua aplicacao. Em vez de consultar a REST API periodicamente, seu endpoint recebe notificacoes instantaneas quando algo importante acontece - uma mensagem chega, uma conversa e encerrada, um contato e criado ou o status de entrega muda. Cada requisicao de webhook e assinada com HMAC para seguranca 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 publico que possa receber requisicoes HTTP POST

Um certificado SSL valido (Let's Encrypt funciona perfeitamente)

Pagina de Webhooks do painel SendSeven com o botao Adicionar Endpoint destacado

Dialogo Adicionar Endpoint com campo de URL HTTPS e inscricoes de eventos no SendSeven

Eventos: Selecione quais eventos receber

Popup Webhook Criado com Sucesso exibindo a chave secreta com botao Copiar

Pagina de detalhes do webhook mostrando URL do endpoint, eventos inscritos, historico de entregas e status de saude 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 e atualizada

Sob demanda via o endpoint de verificacao (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