Providers — execução, respostas e webhooks de métricas

Quando uma jornada envia uma comunicação, existem etapas diferentes entre a decisão do PrismaFlow e a interação da pessoa. A solicitação pode aguardar na fila, ser aceita pelo provider, chegar ao dispositivo e, depois, receber um clique.

Essas etapas não significam a mesma coisa. Entender a diferença ajuda a investigar falhas e evita interpretar uma comunicação aceita como se ela já tivesse sido entregue.

Neste guia, webhook do provider é o retorno usado para informar entrega, clique ou falha. Ele não deve ser confundido com uma ação webhook, na qual o PrismaFlow chama um sistema do negócio para executar uma operação.

O caminho de uma comunicação

Na fila

A ação foi criada e aguarda sua vez de execução. Ela também pode permanecer nessa etapa enquanto respeita uma proteção do canal, como a janela que evita várias comunicações para a mesma pessoa em poucos minutos.

Estar na fila não significa falha. A comunicação ainda não foi enviada ao provider.

Enviada ao provider

O PrismaFlow montou a solicitação e iniciou o envio. Essa é uma etapa técnica e pode durar pouco tempo.

Confirmada

O provider aceitou a solicitação. Quando disponível, o PrismaFlow guarda o identificador retornado pelo provider para relacionar atualizações posteriores à ação correta.

Uma confirmação ainda não prova que a comunicação chegou ao dispositivo. O provider pode aceitar o envio e descobrir mais tarde que o destino está indisponível, que a inscrição deixou de existir ou que outra limitação impediu a entrega.

Entregue

O provider informou que a comunicação chegou ao destino. Esse estado depende da capacidade de metrificação oferecida pelo canal e da configuração do retorno do provider.

Clicada

O provider informou uma interação com a comunicação. Assim como a entrega, essa informação depende dos retornos oferecidos e configurados pelo provider.

Entrega e clique são sinais diferentes. Uma comunicação pode ser entregue e nunca receber interação.

Webhooks de métricas do provider

Alguns resultados só são conhecidos depois que a solicitação inicial terminou. Para enviar essas atualizações, o provider chama um endpoint do PrismaFlow com informações sobre o que aconteceu.

O PrismaFlow relaciona o retorno à comunicação original pelo identificador do provider. Quando a relação é encontrada, o histórico da ação pode avançar para entregue, clicada ou falha.

Hoje, essa visibilidade depende do retorno disponível e configurado para cada provider. A integração com métricas de entrega e clique está em evolução. Por isso, a ausência de uma atualização posterior não deve ser interpretada, sozinha, como prova de que a comunicação falhou.

Tentativas não devem virar comunicações duplicadas

Falhas de rede, indisponibilidade temporária e limites do provider podem exigir uma nova tentativa. O PrismaFlow trata essas situações sem criar uma nova comunicação lógica.

A mesma ação conserva sua chave de idempotência durante as tentativas. O processamento também reconhece uma ação que já saiu da fila, e retornos repetidos do provider são deduplicados.

Essas camadas existem para que uma nova tentativa conclua o envio original, em vez de produzir duas comunicações para a mesma pessoa.

Nem todo erro recebe uma nova tentativa. Uma credencial inválida, um conteúdo incompatível ou outro problema que exige correção não melhora apenas esperando. Nesses casos, a ação falha e apresenta um motivo para investigação.

Falha e supressão são resultados diferentes

Falha

A execução começou, mas não conseguiu ser concluída. Entre as causas possíveis estão:

• credencial inválida;
• configuração ou conteúdo incompatível;
• falha de rede depois das tentativas disponíveis;
• indisponibilidade prolongada ou limite do provider.

O histórico da instância mostra o motivo conhecido. Quando o provider devolve uma resposta útil, ela pode ajudar a identificar a causa.

Supressão

A comunicação não deve ser enviada nas condições atuais. Isso pode acontecer quando o perfil não possui a identidade exigida pela integração, quando a integração está desativada ou quando outra regra de segurança impede o envio.

Uma supressão não significa que o provider recusou a solicitação. Em muitos casos, o PrismaFlow nem chega a chamar o provider.

Como investigar uma comunicação

Comece pela instância da jornada e localize a ação. Observe:

1. o status atual;
2. o motivo da falha ou supressão;
3. quantas tentativas aconteceram;
4. o horário em que a ação foi confirmada, entregue ou clicada;
5. o identificador da comunicação no provider, quando disponível;
6. a resposta apresentada no detalhe da execução.

Se várias ações falharem pela mesma integração, verifique a credencial e a configuração do provider. Se apenas alguns perfis forem suprimidos, compare as identidades exigidas com as identidades existentes nesses perfis.

Quando uma ação está confirmada, mas não possui entrega ou clique, considere três possibilidades: o provider ainda não enviou o retorno, aquele tipo de métrica não está configurado ou o canal não conseguiu observar a etapa posterior.

Boas práticas

1. Não use “confirmada” como sinônimo de “entregue”.
2. Mapeie uma identidade estável conhecida pelo provider.
3. Preserve a mesma ação durante retries; não crie outro envio manual enquanto a primeira execução ainda está sendo processada.
4. Investigue falhas recorrentes pela integração, não apenas por uma instância isolada.
5. Trate a ausência de clique como falta de interação observada, não como prova de que a pessoa ignorou a comunicação.
6. Confirme que os retornos de métricas oferecidos pelo provider estão configurados antes de depender dos indicadores de entrega e clique.

Assuntos relacionados

• Providers — catálogo, configuração e ciclo de vida [blocked]
• Jornadas — ações, variáveis e personalização
• Jornadas — instâncias, histórico e operação
• Jornadas — goals, conversões e resultados

Revisão editorial

• Estado: Em revisão
• Fatos confirmados em: dispatch de providers, histórico de ações, retries, idempotência e ingestão de retornos atuais
• Walkthrough: conhecimento operacional fornecido pelo Darlysson na PF-1378 em 15/08/2026
• Lacunas conhecidas: métricas de entrega e clique dependem da conclusão da integração de callbacks de cada provider