08. Serviço: Webhook de eventos

O serviço Webhook de Eventos é responsável por enviar a um determinado endpoint todos os eventos que ocorreram nas comunicações enviadas pela plataforma.

Segurança

O endpoint deve ser uma URL pública que responda às requisições HTTP/HTTPS.

Também é importante que a URL não esteja num contexto de VPN.

Esse endpoint pode ser autenticado por meio de headers customizados ou receber autorização do tipo basic (user e password).

Envios ao Endpoint

O envio ocorre no momento que os eventos são processados pela plataforma. Trata-se de uma requisição HTTP/HTTPS utilizando o método POST. O conteúdo pode ser um JSON ou XML contendo um ou mais eventos.

O serviço tenta enviar os eventos durante um período de sete dias após a primeira tentativa de envio. O intervalo entre as tentativas de envio é incrementado a cada falha, seguindo a tabela abaixo:

Número de tentativas	Intervalo
1	Imediato
2	1 hora
3	2 horas
4	3 horas
5	5 horas
6	8 horas
6 >	Reinício do intervalo

Após o período de sete dias o envio não ocorrerá mais e os dados “perdidos” podem ser solicitados através do atendimento. Os dados serão gerados em um arquivo no formato .csv e o tempo de geração dependerá do volume em questão.

Tipos de Canais

É possível receber status dos envios de comunicações via webhook pelos seguintes canais:

E-mail
SMS
WhatsApp
Print (impresso)

⚓Tipos de Eventos

Evento	Descrição
Processed	Enviado
Dropped	Não entregue por inconsistência nos dados de contato
Delivered	Recebido
Click	Algum link dentro da mensagem foi clicado
Bounce	Não entregue
Deferred	Entrega adiada temporariamente
Open	Aberto pelo destinatário
SpamReport	Denúncia de que mensagem enviada tratava-se de spam
Unsubscribe	Destinatário optou por se descadastrar da lista de recebimento
SentToProvider	Enviado ao provedor
Reply	Respondido
Read	Mensagem lida pelo destinatário
PrintReleased	Pronto para impressão
Printed	Impresso
PrintRestarted	Impressão reiniciada

💡 Dica:Alguns provedores geram eventos Open/Click (E-mail) e Click (SMS) automaticamente, impossibilitando distingui-los de ações de usuários reais.

Eventos por Canal

Cada canal contém eventos específicos.

⚠️ Atenção: O provedor Gmail não faz distinção entre cliques de bots e cliques de usuários reais, portanto, não é possível identificar a origem dos cliques. Tenha em mente que essa é uma limitação do provedor.

Eventos	E-mail	SMS	WhatsApp Zenvia	WhatsApp LivePerson	RCS	Push	Impresso
Processed (Enviados)	🟢	🟢	🟢	🟢	🟢	🟢	🟢
Dropped (Dropped)	🟢	🟢	🟢	🟢	🟢	🟢	❌
Delivered (Entregues)	🟢	🟢	🟢	🟢	🟢	🟢	❌
Click (Cliques)	🟢 se tiver clique do servidor e shortURL	🟢 se tiver shortURL	🟢 se tiver shortURL	🟢 se tiver shortURL	❌	❌	❌
Bounce (Erros da operadora)	🟢	🟢	🟢	🟢	❌	❌	❌
Deferred	🟢	❌	❌	❌	❌	❌	❌
Open (Abertos)	🟢	❌	❌	❌	❌	🟢	❌
Spam Report	🟢	❌	❌	❌	❌	❌	❌
Unsubscribe	🟢	❌	❌	❌	❌	❌	❌
Sent To Provider	❌	🟢	❌	❌	❌	❌	❌
Reply (Respostas)	❌	🟢	🟢	🟢	❌	❌	❌
Read (Lidos)	❌	❌	🟢	❌	🟢	❌	❌
Posted (Postados)	❌	❌	❌	❌	❌	❌	🟢
Print Released	❌	❌	❌	❌	❌	❌	🟢
Printed (Impressos)	❌	❌	❌	❌	❌	❌	🟢
Print Restarted	❌	❌	❌	❌	❌	❌	🟢

Descrição dos campos

Nome do campo	Descrição	Informações Adicionais
`created`	Data/hora que o evento foi processado pela plataforma.	Formato ISO8601.
`tenantId`	Identificador do tenant.
`tenantName`	Nome do tenant.
`journeyId`	Identificador da jornada.
`journeyVersion`	Identificador da versão da jornada.
`journeyName`	Nome da jornada.
`nodeKey`	Identificador do canal.
`nodeName`	Nome do canal.
`channelKind`	Tipo do canal.
`shootingId`	Identificador do disparo.
`shootingCreated`	Data/Hora que o disparo ocorreu na plataforma.
`shootingCorrelationId`	Identificador único do disparo.	Essa informação é fornecida durante o envio pela API do Jornada. Deve ser utilizada pelo cliente para identificar o disparo dentro de sua plataforma.
`trackingUrl`	Caso seja um evento de clique aqui, será apresentado o link clicado.	Apenas para E-mail, SMS e WhatsApp.
`trackingIp`	Número do IP onde o evento ocorreu. Pode ocorrer para eventos de clique e abertura de e-mail.	Apenas para E-mail, SMS e WhatsApp.
`userAgent`	Perfil de navegação utilizado para abrir o e-mail.	Apenas para E-mail, SMS e WhatsApp. Para mais informações, veja a Wikipedia.
`userAgentBrowserFamily`	Texto que identifica o navegador onde o evento ocorreu.
`userAgentBrowserVersion`	Texto que identifica a versão do navegador onde o evento ocorreu.
`userAgentOSFamily`	Texto que identifica o sistema operacional onde o evento ocorreu.
`userAgentOSVersion`	Texto que identifica a versão do sistema operacional onde o evento ocorreu.
`userAgentDeviceFamily`	Texto que identifica o dispositivo onde o evento ocorreu.
`carrierName`	Nome da operadora do número do telefone que recebeu o SMS.	Essa informação não é fornecida por todas as operadoras.
`recipient`	Destinatário.	Número do telefone ou e-mail do cliente.
`eventType`	Tipo do evento.	Ver Tipos de Eventos.
`bounceType`	Identifica se é um hard bounce ou soft bounce.	Essa informação ocorre apenas para e-mail.
`bounceReason`	Descrição detalhada do motivo do bounce.	Essa informação ocorre apenas para e-mail.
`response`	Texto de uma eventual resposta do destinatário para um SMS recebido.	Essa informação ocorre apenas para SMS.
`eventDate`	Data do evento em GMT.	Formato ISO8601.
`movementDate`	Data do movimento.	Formato ISO8601.
`movementFileName`	Nome do arquivo do movimento.
`movementLot`	Lote do movimento.
`integrationId`	Identificador da requisição feita à API para realização do disparo.	Esse informação também é fornecida na resposta da API.
`integrationCreated`	Data da chamada à API realizada para o disparo.	Formato ISO8601.
`integrationProcessingDate`	Data que a requisição foi processada pela plataforma.
`customerId`	Identificador do cliente.
`customerName`	Nome do cliente.
`documentDescription`	Descrição do documento.
`documentDueDate`	Data de vencimento do documento.	Formato ISO8601.
`properties`	Não é obrigatório e serve apenas para possibilitar que o cliente transite dados pela plataforma até o recebimento no webhook.
`ProviderEventId`	Identificador único de cada evento.
`IsTest`	Identifica se é um teste (true) ou não (false).
`channelCertificatedKind`	Tipo da certificação do canal.	Valores possíveis: None, Standard
`channelCertificatedUrl`	URL do laudo/comprovante da certificação do canal.

Exemplo de retorno em JSON

{
  "Created": "2022-11-08T16:54:25",
  "TenantId": "1abc2efg3hij4klm5nop",
  "TenantName": "EmpresaX",
  "JourneyId": "JRN-67890",
  "JourneyVersion": "v1.0",
  "JourneyName": "XYZ",
  "NodeKey": "ND-98765",
  "NodeName": "Node1",
  "ChannelKind": "Email",
  "ShootingId": "SH-34567",
  "ShootingCreated": "2022-11-08T16:54:25",
  "ShootingCorrelationId": "CR-12345",
  "TrackingUrl": "https://tracking.example.com/track/12345",
  "TrackingIp": "192.168.1.1",
  "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "UserAgentBrowserFamily": "Chrome",
  "UserAgentBrowserVersion": "90.0.4430.93",
  "UserAgentOSFamily": "Windows",
  "UserAgentOSVersion": "10.0",
  "UserAgentDeviceFamily": "Desktop",
  "CarrierName": "CarrierXYZ",
  "Recipient": "[email protected]",
  "EventType": "Click",
  "BounceType": "Hard",
  "BounceReason": "Invalid Email Address",
  "Response": "Success",
  "EventDate": "2022-11-09T12:30:45",
  "ProviderEventId": "EVT-56789",
  "MovementDate": "2022-11-09T13:00:00",
  "MovementFilename": "movement_data_20221109.csv",
  "MovementLot": "LOT-1234",
  "IntegrationId": "INT-34567",
  "IntegrationCreated": "2022-11-08",
  "IntegrationProcessingDate": "2022-11-09T14:00:00",
  "CustomerId": "CUST-67890",
  "CustomerIdentification": "CPF-123.456.789-00",
  "CustomerName": "João Silva",
  "DocumentDescription": "Fatura de Serviços",
  "DocumentDueDate": "2022-12-01",
  "IsTest": true,
  "Properties": {
    "d1idempresax": "AB-12345",
    "d1email": "[email protected]",
    "d1qmnum": "QM-56789",
    "d1parceiro": "ParceiroABC",
    "d1instalacao": "INST-1234",
    "d1cpf_cnpj": "12.345.678/0001-99"
  },
  "ChannelCertificatedKind": "Standard",
  "ChannelCertificatedUrl": "https://arquivo.certificado/123"
}

Como podemos ajudar?