Integração de streaming de eventos

Assistência de desenvolvedor necessária

Você precisará da ajuda da sua equipe de desenvolvimento para configurar a integração. Por favor, compartilhe este guia com eles.

Visão geral da integração

Tipo de integração

Fonte: os dados são enviados do Pushwoosh para o seu sistema via HTTP ou gRPC com base nos gatilhos de eventos configurados.

Como a integração funciona?

O Pushwoosh transmite dados de eventos de comunicação (por exemplo, atividade de push/e-mail) para um endpoint definido pelo cliente. Os dados são enviados em fluxos de lote em intervalos programados ou ao atingir um tamanho mínimo de lote.

Os dados só são enviados se corresponderem aos eventos, plataformas e filtros opcionais selecionados (códigos de campanha/mensagem, atividade ao vivo). O endpoint do cliente deve estar pronto para receber e, opcionalmente, responder com um status.

Glossário

URL do endpoint: Endpoint do lado do servidor que permite receber solicitações. O cliente pode especificar uma porta, se necessário.

Exemplos:

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

Lista de entidades sincronizadas

• Eventos de estatísticas de comunicação (por exemplo, Push Enviado, E-mail Entregue)
• Post events: eventos que seu aplicativo envia para o Pushwoosh via postEvent, transmitidos separadamente dos eventos de estatísticas de comunicação

Casos de uso

• Rastreamento de engajamento em tempo real

Monitore as interações do usuário, como push enviado, e-mail aberto ou mensagem entregue, à medida que acontecem, permitindo visibilidade imediata do desempenho da campanha.

• Integração com análises externas

Transmita eventos para plataformas de análise de terceiros para relatórios e análises centralizados.

• Fluxos de trabalho de usuário automatizados

Acione ações em sistemas externos (como CRMs ou ferramentas de automação de marketing) com base nos comportamentos do usuário, por exemplo, envie uma mensagem de acompanhamento quando um usuário abrir um e-mail.

Configurando a integração

Para configurar a integração:

1. Na sua conta Pushwoosh, vá para Configurações > Integrações de terceiros, encontre Integração de streaming de eventos e clique em Configurar.

2. Na janela que se abre, preencha os campos necessários.

Inserir URL do endpoint

No campo URL do endpoint, insira a URL completa para onde os eventos serão enviados, incluindo o protocolo e a porta, se aplicável.

Exemplo

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

Selecionar eventos

No menu suspenso Eventos, selecione pelo menos um evento. Se nenhum for selecionado, a validação falhará. A lista de eventos é gerenciada pelo backend e pode mudar com o tempo.

Fornecer credenciais de autorização

Se exigido pelo seu servidor, insira o valor completo para o cabeçalho Authorization no campo Autorização.

Exemplos:

• Bearer your_token_here

• Basic base64encoded_credentials

Nota

O valor é inserido como está no cabeçalho Authorization (HTTP) ou nos metadados gRPC. Certifique-se de que há um espaço entre o esquema de autenticação e o token.

Escolher tipo de transporte

No menu suspenso Tipo de transporte, escolha o protocolo de entrega para a transmissão de eventos: HTTP ou gRPC. Cada um tem comportamento e configuração específicos.

HTTP

Com o tipo de transporte HTTP, o Pushwoosh envia dados em lotes com base em uma das seguintes condições:

• Pelo menos 100 eventos estão prontos para serem enviados, ou

• Uma hora se passou desde a última transmissão.

Após o envio dos dados, a conexão é fechada assim que uma resposta bem-sucedida é recebida.

Se o servidor responder com um erro 5xx, o Pushwoosh tentará novamente a solicitação de acordo com a política de nova tentativa definida.

Mecanismo de nova tentativa

Tentativa	Atraso
1ª	1 segundo
2ª	3 segundos após a 1ª tentativa
3ª	8 segundos após a 2ª tentativa

Se todas as novas tentativas falharem, a solicitação é descartada.

Tempo limite

O tempo limite padrão para uma solicitação é de 30 segundos. Isso pode ser personalizado mediante solicitação via suporte.

Ver exemplo

gRPC

O tipo de transporte gRPC usa streaming bidirecional para a transmissão de dados. Saiba mais na documentação do gRPC.

Um fluxo é aberto quando uma das seguintes condições é atendida:

• Pelo menos 1.000 eventos estão prontos para entrega
• Uma hora se passou desde que o último fluxo foi aberto

O fluxo é fechado após o envio dos eventos. Isso garante que um novo fluxo não seja aberto para cada evento individual em um curto período de tempo.

Ver especificação protobuf

Mecanismo de nova tentativa
Cada evento inclui um uuid único. Se um evento falhar:

1. A resposta deve incluir um status diferente de "Success"
2. O uuid original da solicitação deve ser incluído

O Pushwoosh tentará novamente a entrega com base nesta resposta.

Configurações de conexão

Opções avançadas como TLS, keep-alive ou políticas de nova tentativa são configuradas manualmente via suporte e podem exigir envolvimento de desenvolvimento.

Habilitar post events

Este botão está desativado por padrão, então apenas os eventos de estatísticas de comunicação são transmitidos. Para também transmitir eventos que seu aplicativo envia para o Pushwoosh via postEvent, ative o botão Permitir post events.

No campo Post events que aparece, selecione quais dos eventos da sua conta devem ser transmitidos. Pelo menos um evento é necessário enquanto o botão estiver ativado. Se sua conta ainda não enviou nenhum evento, esta lista estará vazia até que você chame postEvent pelo menos uma vez.

Nota

Os post events são enviados para a mesma URL do endpoint inserida acima e chegam a ela independentemente da plataforma: as seções Plataformas e Filtros avançados abaixo se aplicam apenas aos eventos de estatísticas de comunicação, não aos post events.

Selecionar plataformas

Na seção Plataformas, selecione pelo menos uma plataforma para ativar o streaming de eventos.

As plataformas suportadas incluem:

• iOS, Android, macOS, Windows, Amazon, Safari
• Chrome, Firefox, Internet Explorer, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

Configurar filtros avançados

Na seção Filtros avançados, refine os critérios de entrega de eventos usando filtros:

• Eventos de atividade ao vivo: Habilite para receber eventos de atividade ao vivo. Estes eventos contêm apenas metadados, incluindo live_activity_id.

• Filtros de campanha: Filtre por código de campanha. Apenas eventos vinculados a essas campanhas serão entregues.

• Filtros de mensagem: Filtre por código de mensagem. Apenas eventos vinculados a essas mensagens serão entregues.

Após preencher todos os campos obrigatórios, clique no botão Aplicar para salvar e ativar sua integração.

Nota

As alterações de configuração entrarão em vigor em até 15 minutos após o envio.

Dica

Para configurações avançadas, como tempos limite personalizados ou configurações de gRPC, por favor, entre em contato com o suporte.

Detalhes da solicitação e exemplo

Endpoint	https://exampleclientendpoint.com/webhook_endpoint
Requisição HTTP	POST
Autenticação	Não
Tipo de requisição	Fonte
Significado da requisição	Enviar requisições para o endpoint do webhook
Cabeçalhos	Content-Type: application/json

Exemplo de corpo da requisição

{
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new",
  "attributes": null
}

Atributos

Entre os eventos de estatísticas de comunicação, attributes é preenchido apenas para eventos de push, com conteúdo específico do canal (Android, iOS, etc.) para a plataforma para a qual o push foi enviado. Eventos de e-mail e SMS carregam apenas os campos de nível superior (event_name, platform, payload, etc.). attributes é null para esses eventos. Dentro de um objeto attributes preenchido, os campos fora da plataforma do próprio evento são omitidos em vez de serem enviados como valores vazios. Consulte webhook.proto para a lista completa de campos.

Um post event carrega seus pares de chave/valor de atributo em attributes.event_attributes. message_code e payload permanecem vazios, porque um post event não está vinculado a uma mensagem ou campanha.

Cuidado

attributes.geozone está obsoleto: a propriedade de origem é um objeto, não um número, então este campo nunca carregou um valor real. Leia a geozone real de attributes.geozone_data. O campo antigo permanece no contrato para clientes com stubs gRPC existentes.

Resposta
No momento, o código de resposta e o corpo são ignorados.

Como você sabe que a integração está funcionando?

Você começará a receber solicitações do Pushwoosh no seu endpoint configurado.