Webhooks permitem que a StackZap envie uma solicitação HTTP para sua aplicação quando ocorre um evento. Com eles, seu sistema pode reagir a mensagens recebidas, atualizações de status e mudanças de conexão sem consultar a API repetidamente.
Prepare o endpoint receptor
Crie uma rota HTTPS pública que aceite requisições POST com Content-Type: application/json. Ela deve ler o corpo, validar a assinatura antes de confiar nos dados e responder com um status de sucesso assim que a requisição estiver aceita para processamento. Se sua aplicação demorar muito, coloque o trabalho em uma fila interna e responda rapidamente.
Cadastre o webhook
Na API self-hosted, a referência documenta operações para criar e consultar webhooks. Um cadastro inclui URL, segredo, eventos e estado ativo. No Cloud, use as opções disponíveis no painel do ambiente e a documentação da versão correspondente. Guarde o segredo do webhook em um cofre de credenciais separado da API Key.
Eventos documentados no código incluem message.received, message.status, connection.update e group.update. Confirme na documentação quais eventos são emitidos pela sua versão e quais estão disponíveis apenas para simulação ou teste.
Entenda o formato
As entregas usam um envelope com event, delivery_id, timestamp e data. Os headers também identificam evento, entrega, horário e assinatura. O conteúdo de data depende do evento. Projete o receptor para ignorar campos extras e validar os campos necessários antes de executar ações.
Webhook como entrada de eventos
Um webhook permite que a StackZap informe sua aplicação quando ocorre um evento, evitando que seu sistema consulte a API sem parar. O endpoint receptor deve estar acessível pela rede e preparado para receber requisições HTTP conforme a configuração da sua instalação. Use uma URL dedicada, com HTTPS, e encaminhe o evento para uma fila ou processo interno quando o tratamento não for rápido.
Pense no endpoint público como uma porta de entrada, não como o lugar para executar toda a lógica de negócio. O handler valida a origem e a estrutura, salva o recebimento de forma durável e responde com rapidez. Um worker separado processa a mensagem, atualiza seu sistema e chama outros serviços. Essa separação ajuda a evitar que uma indisponibilidade temporária de CRM, banco secundário ou automação impeça a confirmação da entrega do webhook.
Confira os nomes de eventos e formato do corpo na documentação da StackZap da versão usada. Os eventos e campos podem mudar conforme recursos habilitados. Não crie dependência em propriedades não documentadas nem assuma que todo evento contém texto, telefone ou identificador em um mesmo caminho JSON.
Configure um receptor confiável
O endpoint deve validar método, tipo de conteúdo, tamanho máximo do corpo e campos essenciais. Rejeite ou coloque em quarentena payloads que não puder processar com segurança. Limite o tamanho para reduzir risco de exaustão e desative logs automáticos de corpo completo se contiverem números, mensagens ou outros dados pessoais.
O receptor deve lidar com duplicatas. Redes podem repetir entregas e sua aplicação também pode receber um evento mais de uma vez após reinicialização. Use o identificador de entrega fornecido, quando presente, como chave de deduplicação. Armazene o envelope e o estado de processamento numa transação ou mecanismo equivalente antes de responder. Se não houver identificador estável no payload, escolha uma chave de negócio apropriada sem presumir que corpo idêntico sempre significa duplicata legítima.
Não dependa de ordenação global dos eventos. Um estado posterior pode chegar antes de outro por latência, retry ou processamento concorrente. Salve timestamps e IDs documentados; ao aplicar a mudança, compare o estado atual e a sequência de negócio. Faça operações idempotentes quando possível: processar o mesmo evento duas vezes não deve criar dois contatos ou duas ações externas.
Pipeline recomendado
- 01Ler o corpo bruto e validar a assinatura
- 02Persistir evento e ID de entrega
- 03Responder rapidamente ao remetente
- 04Processar em fila com deduplicação
- 05Registrar resultado e tratar falhas
Leia o corpo bruto antes de converter JSON se a validação HMAC da sua versão for calculada sobre os bytes originais. Reformatar ou serializar novamente o objeto pode alterar espaços e ordem de propriedades, produzindo outra sequência de bytes e uma assinatura incompatível. Consulte o artigo de validação HMAC e o manual técnico.
Etapas de um receptor confiável
| Etapa | Ação | Resultado esperado |
|---|---|---|
| Receber | Aceitar a requisição HTTPS e preservar o corpo original. | Evento disponível para validação. |
| Validar | Conferir assinatura e campos necessários. | Payload confiável para a aplicação. |
| Persistir | Registrar envelope e identificador de entrega. | Evento recuperável após uma falha. |
| Processar | Enfileirar trabalho e aplicar idempotência. | Efeitos executados sem duplicar a entrega. |
Responda com clareza e gerencie falhas
Defina quais respostas HTTP sua configuração considera sucesso. A resposta deve indicar que a aplicação recebeu e persistiu o evento, e não necessariamente que concluiu todas as etapas externas. Evite retornar sucesso antes de salvar o evento se não puder recuperá-lo após uma queda. Ao mesmo tempo, mantenha o processamento pesado fora da requisição para reduzir timeout.
Se o endpoint falhar, acompanhe o mecanismo de retentativas documentado para sua instalação. Não presuma um intervalo fixo sem verificar a referência. Corrija rapidamente a causa: TLS inválido, DNS, firewall, indisponibilidade do serviço ou erro no parser. Monitore a idade do evento mais antigo não processado e o número de falhas por classe. Uma fila crescente pode mostrar problema mesmo quando a URL responde HTTP 200.
Retentativas podem duplicar eventos; por isso, desenhe o processamento para ser idempotente. Para efeitos externos, grave uma intenção antes de enviar e associe resultado e ID de evento. Se a operação externa não permite idempotência, mantenha reconciliação e revisão para eventos com resultado incerto. Não deixe uma exceção isolada travar permanentemente o worker; mova o evento para uma fila de falhas com contexto redigido e procedimento de reprocessamento.
Segurança do endpoint
Além da assinatura, use HTTPS e controle de acesso de rede quando sua infraestrutura permitir. A assinatura confirma integridade e origem conforme o mecanismo documentado, mas não substitui proteção contra replay ou autorização da lógica. Valide timestamps e política de idade apenas se o formato e o protocolo suportarem essa checagem. Não invente janela de tolerância sem confirmar como o servidor assina e envia.
Mantenha o segredo HMAC em cofre ou configuração restrita. Não o inclua na URL, no frontend, em imagens ou no repositório. Restrinja permissões de leitura e tenha procedimento para atualizar o segredo. Proteja os endpoints contra excesso de requisições e imponha limites de corpo e tempo. Faça validação estrita do JSON, mas preserve o corpo original para a checagem criptográfica.
Eventos podem carregar dados pessoais e conteúdo de conversas. Colete e guarde somente o necessário. Limite quem consulta logs e payloads persistidos, defina uma retenção compatível com a finalidade e o contrato e oculte conteúdo em ferramentas de observabilidade. Em relatórios, prefira contagens e identificadores internos.
Teste a integração em etapas
Comece com endpoint local ou ambiente de teste sem efeitos reais. Verifique a conectividade HTTPS a partir do ambiente que enviará o webhook, registre o recebimento e confirme a assinatura usando o método oficial. Depois simule payloads válidos, inválidos, duplicados, grandes demais e fora de ordem. Teste uma indisponibilidade do processador downstream e confirme que o evento persiste e pode ser retomado.
Não use um payload copiado de produção com dados reais em ferramentas externas. Crie exemplos sintéticos que preservem o schema sem números e textos de cliente. Testes devem assegurar que o mesmo ID não cria ações duplicadas, que uma assinatura incorreta é rejeitada e que a resposta HTTP não confirma eventos perdidos.
Monitoramento e diagnóstico
Acompanhe o volume por tipo de evento, taxa de assinatura inválida, latência de recebimento, tempo de processamento, repetição, falhas finais e tamanho da fila. Defina alertas para mudança incomum, mas evite alertar por cada evento. As métricas devem permitir diferenciar problema na entrega da StackZap, na entrada pública, no processamento interno ou no serviço downstream.
Ao pedir suporte, informe ambiente, URL receptora sem segredos, horário com fuso, ID de entrega, tipo do evento e resposta HTTP. Remova cabeçalho de assinatura, segredo HMAC e informações pessoais do payload. No Cloud, a URL de callback e as configurações devem ser confirmadas pelo painel do ambiente; o self-hosted exige que o operador cuide de DNS, TLS, firewall, processo e armazenamento.
Checklist de produção
- URL HTTPS estável e acessível pelo ambiente StackZap.
- Assinatura verificada sobre o corpo bruto conforme manual.
- Segredo armazenado em configuração segura e com acesso limitado.
- Evento salvo antes da resposta de sucesso.
- Deduplicação e processamento idempotente implementados.
- Processamento pesado desacoplado por fila.
- Retry, falha permanente e reprocessamento observáveis.
- Limites de tamanho, tempo e taxa definidos.
- Logs redigem mensagens, números, chaves e assinaturas.
- Retenção e acesso aos payloads estão definidos.
Separe recebimento de resposta ao usuário
Um webhook técnico confirma a transferência entre sistemas; não é necessariamente uma resposta de atendimento. O endpoint valida, persiste e encaminha o evento, enquanto uma regra de negócio decide se haverá resposta automática ou criação de tarefa. Não responda a todo evento sem checar tipo, estado e contexto, pois atualizações de conexão e status também podem chegar pelo callback.
Se uma mensagem recebida aciona um chatbot, aplique autenticação, autorização, validação de entrada e limites no backend. Trate conteúdo recebido como dado não confiável: texto pode conter instruções maliciosas para um agente, links ou tentativas de explorar seu sistema. Restrinja ferramentas disponíveis e não passe API Keys ao modelo. Registre qual regra acionou a resposta, minimizando conteúdo.
Reprocesse sem repetir efeitos
Uma fila durável permite reprocessar depois de uma falha, mas exige idempotência. Salve ID do evento, estado e tentativa. Antes de repetir, verifique se o sistema já criou conversa, pedido ou notificação. Se a etapa externa tem resultado desconhecido, encaminhe para reconciliação em vez de fazer retry automático.
Teste o receptor com payload válido, assinatura incorreta, duplicata e serviço downstream indisponível. Confirme que a resposta HTTP corresponde ao que foi persistido e que o operador consegue encontrar falhas sem abrir payloads confidenciais.
Separe recebimento de resposta ao usuário
Um webhook técnico confirma a transferência entre sistemas; não é necessariamente uma resposta de atendimento. O endpoint valida, persiste e encaminha o evento, enquanto uma regra de negócio decide se haverá resposta automática ou criação de tarefa. Não responda a todo evento sem checar tipo, estado e contexto, pois atualizações de conexão e status também podem chegar pelo callback.
Se uma mensagem recebida aciona um chatbot, aplique autenticação, autorização, validação de entrada e limites no backend. Trate conteúdo recebido como dado não confiável: texto pode conter instruções maliciosas para um agente, links ou tentativas de explorar seu sistema. Restrinja ferramentas disponíveis e não passe API Keys ao modelo. Registre qual regra acionou a resposta, minimizando conteúdo.
Reprocesse sem repetir efeitos
Uma fila durável permite reprocessar depois de uma falha, mas exige idempotência. Salve ID do evento, estado e tentativa. Antes de repetir, verifique se o sistema já criou conversa, pedido ou notificação. Se a etapa externa tem resultado desconhecido, encaminhe para reconciliação em vez de fazer retry automático.
Teste o receptor com payload válido, assinatura incorreta, duplicata e serviço downstream indisponível. Confirme que a resposta HTTP corresponde ao que foi persistido e que o operador consegue encontrar falhas sem abrir payloads confidenciais.
Evite processar duas vezes
Uma rede instável pode fazer sua aplicação receber novamente uma entrega. Use delivery_id como chave de idempotência: grave que ela foi processada e não repita efeitos colaterais para o mesmo identificador. Mantenha logs com ID, evento e resultado, sem registrar segredos ou conversas inteiras sem necessidade.
Para testar, use a função de teste da interface ou o endpoint de teste documentado e verifique a assinatura, a resposta HTTP e o registro de entregas. Consulte a referência StackZap para o schema atual dos eventos.
Separe recebimento de resposta ao usuário
Um webhook técnico confirma a transferência entre sistemas; não é necessariamente uma resposta de atendimento. O endpoint valida, persiste e encaminha o evento, enquanto uma regra de negócio decide se haverá resposta automática ou criação de tarefa. Não responda a todo evento sem checar tipo, estado e contexto, pois atualizações de conexão e status também podem chegar pelo callback.
Se uma mensagem recebida aciona um chatbot, aplique autenticação, autorização, validação de entrada e limites no backend. Trate conteúdo como dado não confiável: texto pode conter instruções maliciosas para um agente, links ou tentativas de explorar o sistema. Restrinja ferramentas disponíveis e não passe API Keys ao modelo.
Reprocesse sem repetir efeitos
Uma fila durável permite reprocessar depois de falha, mas exige idempotência. Salve ID do evento, estado e tentativa. Antes de repetir, verifique se o sistema já criou conversa, pedido ou notificação. Se a etapa externa tem resultado desconhecido, encaminhe para reconciliação em vez de retry automático.
Teste o receptor com payload válido, assinatura incorreta, duplicata e serviço downstream indisponível. Confirme que a resposta HTTP corresponde ao que foi persistido e que o operador consegue encontrar falhas sem abrir payloads confidenciais.