Integração de streaming de eventos

É necessária a ajuda do desenvolvedor

Você precisará da ajuda de 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 funciona a integração?

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ão enviados apenas 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 o recebimento de requisiçõ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)

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 Settings > 3rd party Integrations, encontre Event streaming integration e clique em Configure.

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

Insira o URL do endpoint

No campo Endpoint URL, insira o URL completo 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

Selecione os eventos

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

Forneça as credenciais de autorização

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

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 haja um espaço entre o esquema de autenticação e o token.

Escolha o tipo de transporte

No menu suspenso Transport type, 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 requisiçã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 requisição é descartada.

Timeout

O timeout padrão para uma requisiçã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 stream é 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 stream foi aberto

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

Ver especificação do 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 requisiçã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 o envolvimento do desenvolvimento.

Selecione as plataformas

Na seção Platforms, 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, Baidu, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

Configure filtros avançados

Na seção Advanced filters, refine os critérios de entrega de eventos usando filtros:

• Live activity events: Habilite para receber eventos de atividade ao vivo. Esses eventos contêm apenas metadados, incluindo live_activity_id.

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

• Message filters: 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 Apply 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 timeouts personalizados ou configurações gRPC, por favor, entre em contato com o suporte.

Detalhes e exemplo da requisição

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

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

Como saber se a integração está funcionando?

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