Integração de streaming de eventos

Assistência de desenvolvedor necessária

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 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ã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 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)

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.

Insira a 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

Selecione os 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.

Forneça as 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.

Escolha o 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 repetição definida.

Mecanismo de repetição

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

Se todas as 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 através do 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 do protobuf

Mecanismo de repetição 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 repetição são configuradas manualmente através do suporte e podem exigir o envolvimento do desenvolvimento.

Selecione as 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, Baidu, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

Configure 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. Esses 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 gRPC, por favor, entre em contato com o suporte.

Detalhes da solicitação e exemplo

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

Exemplo de corpo da solicitaçã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 solicitações do Pushwoosh em seu endpoint configurado.