Providers — catálogo, configuração e ciclo de vida

Providers conectam o PrismaFlow aos serviços que executam ações fora da plataforma. Uma jornada pode usar essas conexões para enviar um push ou chamar um endpoint do negócio, por exemplo.

Antes de configurar uma conexão, é importante separar três conceitos:

• Provider: capacidade disponível no catálogo, como OneSignal ou Webhook;
• Integração: configuração criada para usar aquele provider dentro de um app do PrismaFlow;
• Credencial: chave ou segredo que permite à integração se autenticar ou assinar uma requisição.

A tela atual usa o nome Credenciais para listar as integrações. O conceito é mais amplo: além do segredo, cada item possui provider, canal, nome, configurações e mapeamento de identidade.

O catálogo disponível

O catálogo informa quais providers o PrismaFlow sabe usar e quais dados cada um exige. Atualmente, ele apresenta:

• OneSignal, no canal de push;
• Webhook, para requisições HTTP enviadas a um sistema externo.

O catálogo não representa uma conexão pronta. Ele funciona como um modelo. A integração passa a existir somente depois que você escolhe o provider e informa as configurações do seu ambiente.

Mais de uma integração pode usar o mesmo provider

Uma operação pode possuir mais de um app do PrismaFlow, e cada app pode possuir várias integrações do mesmo provider. Essa separação é útil quando existem:

• mais de um aplicativo móvel ou site;
• marcas ou produtos diferentes;
• ambientes separados;
• públicos administrados por áreas distintas;
• destinos de webhook com responsabilidades diferentes.

Imagine um marketplace que envia eventos de compradores e vendedores para o mesmo app do PrismaFlow. Compradores podem receber pushes pelo aplicativo de compras. Vendedores podem usar outro aplicativo e receber alertas operacionais por uma integração diferente. Um webhook separado ainda pode comunicar sistemas de risco ou atendimento.

Por isso, use nomes que revelem destino e finalidade, como:

• OneSignal — Compradores;
• OneSignal — Vendedores;
• Webhook — Benefícios;
• Webhook — Alertas operacionais.

Um nome claro reduz o risco de escolher a conexão errada ao configurar templates e jornadas.

Configurar uma integração

O fluxo geral possui três partes.

1. Conexão

Escolha o provider e dê um nome à integração. O provider e o canal não podem ser trocados depois da criação. Se precisar mudar de tecnologia ou canal, crie outra integração.

2. Configuração

Cada provider solicita dados próprios.

Para OneSignal, a configuração inclui o App ID, os idiomas atendidos e a API key com acesso ao app correto.

Para Webhook, ela inclui a URL base HTTPS, o timeout, headers comuns e, quando usado, o segredo de assinatura. O método, caminho e conteúdo de cada chamada pertencem ao template e à ação, não precisam gerar uma integração nova para cada endpoint.

3. Mapeamento de identidade

O mapeamento define qual identidade do perfil corresponde à pessoa no sistema de destino.

Escolha um identificador estável conhecido pelos dois lados. Se o OneSignal usa o ID do cliente como external_id, mapeie o mesmo tipo de identidade no PrismaFlow.

Nos webhooks, o valor mapeado é enviado por padrão no header X-PrismaCDP-User. Outras identidades ou dados podem ser incluídos no body, em query parameters ou em headers definidos pelo template quando o caso exigir.

Se a identidade escolhida não existir no perfil, aquela ação não terá como identificar corretamente o destinatário. Garanta que a integração de eventos envia esse identificador antes de depender dele numa jornada.

Validar não significa a mesma coisa para todo provider

A validação confirma o que o adapter daquele provider consegue verificar.

OneSignal

O PrismaFlow faz uma chamada ao OneSignal para confirmar se o App ID e a API key permitem acessar o app configurado.

Uma validação bem-sucedida mostra que a conexão respondeu naquele momento. Ela não garante que todo perfil futuro possuirá o external_id necessário para receber push.

Webhook

O PrismaFlow valida a estrutura da configuração, o uso de HTTPS e o mapeamento de identidade. Ele não chama o endpoint durante essa validação.

Portanto, uma validação bem-sucedida de webhook não garante que o servidor esteja disponível, aceite determinado payload ou responda com sucesso. Use o teste de ação e acompanhe as primeiras instâncias para validar o comportamento real.

Ciclo de vida

Rascunho

A integração foi criada, mas ainda não pode ser usada para novos envios. Complete a configuração e execute a validação.

Ativa

A integração foi validada e liberada para uso. Templates e jornadas podem depender dela.

Desativada

A integração foi temporariamente retirada de uso. Ela pode ser revalidada e ativada novamente.

Antes de desativar, verifique jornadas e templates dependentes. Ações futuras que alcançarem uma integração indisponível não serão enviadas. O PrismaFlow bloqueia a operação comum quando encontra jornadas ativas usando aquela conexão; uma intervenção forçada deve ser reservada a incidentes.

Arquivada

A integração foi encerrada de forma definitiva. Ela permanece no histórico, mas não volta a ser usada.

Remova ou substitua suas dependências antes de arquivar. O arquivamento não desfaz ações antigas nem apaga registros produzidos pela integração.

Alterar e validar novamente

Nome, configurações e mapeamento podem mudar sem trocar a identidade da integração. O provider e o canal permanecem os mesmos.

Depois de mudar App ID, URL, headers, idiomas ou mapeamento, valide novamente antes de confiar a conexão a uma jornada. Uma validação anterior descreve a configuração verificada naquele momento, não qualquer alteração feita depois.

Rotacionar credenciais

Trocar uma credencial é uma operação de segurança. Use-a quando uma chave expirar, for revogada, vazar ou fizer parte de uma rotação preventiva.

O novo segredo substitui o anterior para todos os próximos envios, inclusive os produzidos por jornadas já publicadas. A rotação não exige redesenhar cada jornada.

Credenciais salvas não voltam a aparecer na interface ou na API. Ao editar uma integração, escolha explicitamente a troca e informe o novo valor.

Depois da rotação, valide a integração novamente e acompanhe os primeiros envios.

Assinar webhooks

Quando um webhook precisa provar que a requisição veio do PrismaFlow, configure um segredo compartilhado. O PrismaFlow usa esse segredo para gerar uma assinatura HMAC-SHA256 do body e enviá-la no header configurado.

O servidor receptor precisa:

1. ler o body recebido sem alterá-lo;
2. calcular a assinatura com o mesmo segredo;
3. comparar o resultado de forma segura;
4. rejeitar a requisição quando a assinatura não for válida.

Um header fixo não substitui essa verificação. Headers comuns podem carregar identificação e contexto, mas a autenticidade da requisição deve ser confirmada pela assinatura.

O PrismaFlow também envia uma chave de idempotência. O destino deve usá-la para evitar repetir uma operação quando houver nova tentativa da mesma chamada.

Boas práticas

1. Separe integrações quando públicos, apps, marcas ou destinos possuírem gestões diferentes.
2. Use um nome que identifique provider, público e finalidade.
3. Mapeie uma identidade estável que o sistema de destino realmente conheça.
4. Valide depois de criar e sempre que mudar a configuração.
5. Não interprete a validação estrutural de webhook como teste de disponibilidade.
6. Use assinatura HMAC e valide-a no servidor receptor.
7. Trate a chave de idempotência no webhook.
8. Rotacione credenciais sem editar templates ou duplicar jornadas.
9. Consulte os usos antes de desativar ou arquivar.
10. Acompanhe as primeiras execuções depois de uma mudança importante.

Assuntos relacionados

• Templates — conteúdo, camadas, respostas, versões e ciclo de vida
• Providers — execução, respostas e webhooks de métricas [blocked]
• Jornadas — ações, variáveis e personalização
• Jornadas — instâncias, histórico e operação
• Identidades e formação de perfis

Revisão editorial

• Estado: Em revisão
• Fatos confirmados em: catálogo, adapters, lifecycle, secret store e dashboard atuais
• Walkthrough: conhecimento operacional fornecido pelo Darlysson na PF-1377 em 15/08/2026
• Lacunas conhecidas: dashboard v1, rotação imediata, referências indiretas e versionamento precisam de conciliação interna