Configure webhooks de depoimentos enviados

Preparar um endpoint de recebimento

Webhooks enviam informações sobre novos depoimentos de rotas de criação suportadas para outro serviço. Você precisa de um plano com webhooks, permissão para editar o espaço e um receptor HTTPS acessível publicamente. Localhost, nomes de host locais e endereços de rede privada não são suportados pela validação de URL do painel.

Para Zapier ou Make, crie primeiro um gatilho de webhook de recebimento e copie seu URL HTTPS. Não conecte uma automação voltada ao cliente antes de verificar a carga útil real e os cabeçalhos de autenticação que ela receberá.

Salve e teste a conexão

1. Abra Webhooks na barra lateral. Ele abre Configurações do espaço de trabalho → Avançado.
2. Insira o URL do webhook e escolha Salvar configurações do webhook. Armazene o segredo de assinatura gerado com segurança no servidor de recebimento. Nunca coloque-o no código do navegador, em capturas de tela ou em registros públicos.
3. Escolha Enviar evento de teste. O painel envia um evento webhook.test assinado. Verifique se o receptor retorna uma resposta 2xx.
4. Inspecione a solicitação antes de mapear os campos. Um teste de painel bem-sucedido verifica a solicitação de teste assinada; as entregas de formulários de coleta atualmente utilizam um formato diferente, descrito abaixo.

Entenda os dois formatos de entrega atuais

Os eventos de teste do painel usam um envelope assinado por HMAC com campos de id, tipo, criação e dados. Os cabeçalhos incluem Socialjuice-Event, Socialjuice-Delivery, Socialjuice-Timestamp e Socialjuice-Signature. Um evento de criação assinado usa testimonial.created; o teste do painel usa webhook.test.

O serviço de coleta atual envia o segredo configurado em X-Webhook-Secret por meio de HTTPS. Não anexa os cabeçalhos HMAC nem o envelope assinado. As cargas úteis da coleção podem conter campos de depoimento diretamente ou dentro de um objeto de depoimento, dependendo do caminho da coleta. Inspecione uma solicitação real antes de mapear nome, email, uuid e conteúdo de depoimento. Não presuma que a carga de teste do painel corresponde a uma coleção real.

Autenticar e lidar com ambos os formatos

Para solicitações assinadas, verifique HMAC SHA-256 sobre <timestamp>.<raw_request_body>, compare o resumo em tempo constante e rejeite carimbos de data/hora obsoletos. Para solicitações de coleta, compare X-Webhook-Secret com o segredo configurado em seu servidor. Rejeite uma solicitação que não passe na autenticação exigida para seu formato.

O formato de segredo compartilhado não fornece proteção de reprodução de carimbo de data/hora e ID de entrega de eventos assinados. Desduplicar solicitações de coleta com o depoimento uuid no contexto do espaço correto, quando disponível. Para eventos assinados, use Socialjuice-Delivery ou o ID do envelope. Passe apenas os campos do cliente que seu fluxo de trabalho downstream precisa.

Limites de entrega e solução de problemas

Retorne uma resposta 2xx imediatamente. O remetente do painel assinado faz até três tentativas no total, com um tempo limite de 10 segundos por tentativa. O remetente da coleção atual faz uma única solicitação sem esse loop de nova tentativa. Não presuma que as novas tentativas do remetente assinado se aplicam a entregas de formulários de cobrança.

Se a ferramenta de recebimento não puder validar o cabeçalho necessário, coloque uma etapa de verificação em seu próprio servidor antes de acionar ações confidenciais. Um webhook indica criação, não uma nova concessão de consentimento para publicação. Revise a visibilidade pública e o consentimento separadamente.

Gire ou desative a conexão

Se o segredo for exposto, use Rotate secret e atualize todos os receptores imediatamente. Isso altera o segredo usado por ambos os formatos de entrega. Para desativar a entrega, limpe o URL do Webhook e salve. Mantenha o antigo segredo longe de registros públicos e capturas de tela.