Como receber avisos com webhooks?
Um webhook é um aviso automático: sempre que um cliente faz alguma coisa (escreve-lhe no chat, termina um treino, comenta um exercício…), o TrainerStudio chama um endereço web (um URL) indicado por si. Assim, o seu agente de IA, a sua automatização do Zapier ou do Make, ou o seu próprio sistema ficam a saber de imediato, sem terem de perguntar de poucos em poucos minutos.
Não precisa de saber programar: a ferramenta que quer ligar dá-lhe um URL e basta colá-lo no TrainerStudio. Os detalhes técnicos estão na documentação para programadores (em inglês).
1. Abra o separador Webhooks
Vá a Seu app → Desenvolvedores no menu lateral (também está em Configuracoes → Desenvolvedores) e abra o separador Webhooks.
Só o titular da conta pode gerir os webhooks.
2. Adicione um endpoint
Um endpoint é o URL que recebe os avisos.
- Clique em Adicionar endpoint.
- Em URL do endpoint, cole o endereço que a sua ferramenta lhe deu. Tem de começar por
https://. - Em Descrição, escreva algo que o ajude a reconhecê-lo: «Zapier, novas mensagens», «Agente de IA».
- Escolha o que quer receber:
- Todos os eventos: recebe tudo, incluindo os tipos de evento que adicionarmos mais tarde.
- Só os eventos que eu escolher: seleciona os que lhe interessam.
- Guarde.
Pode ter até 10 endpoints. Crie um por ferramenta: se deixar de usar uma, elimina apenas o dela.
Eventos disponíveis
| Evento | Quando é enviado |
|---|---|
| Mensagem de chat recebida | Um cliente escreve-lhe no chat da app |
| Treino concluído | Um cliente termina o treino do dia |
| Comentário num treino | Um cliente deixa um comentário, uma foto ou um vídeo num exercício |
| Métrica registada | É registado um valor numa métrica de um cliente |
| Tarefa concluída | Um cliente conclui uma tarefa |
| Foto de progresso enviada | Um cliente envia uma foto de progresso |
| Formulário respondido | Um cliente responde a um formulário |
O aviso diz o que aconteceu e com que cliente, mas não inclui o conteúdo (nem o texto da mensagem nem as medidas). A sua ferramenta consulta os detalhes com o seu próprio acesso à sua conta.
3. Copie o segredo de assinatura
Ao criar o endpoint aparece a janela Copie seu segredo de assinatura. O segredo (começa por whsec_) permite à sua ferramenta confirmar que o aviso vem mesmo do TrainerStudio.
- Só é mostrado desta vez. Copie-o e cole-o na sua ferramenta antes de clicar em Já copiei.
- Se a sua ferramenta não pedir nenhum segredo (acontece com muitas automatizações simples), pode continuar sem o usar.
- Se o perder, gire o segredo para obter um novo.
4. Envie um evento de teste
Na página do endpoint, clique em Enviar evento de teste. Em poucos segundos vê como a sua ferramenta respondeu:
- Entregue: está tudo a funcionar.
- Com falha: vê o motivo (o URL não responde, demora mais de 10 segundos, devolve um erro…). Verifique o URL na sua ferramenta e tente de novo.
5. Consulte os envios
A página de cada endpoint mostra:
- As estatísticas dos últimos 7 ou 30 dias: taxa de sucesso, tempo de resposta e envios por dia.
- O Registro de envios: cada aviso enviado nos últimos 30 dias. Abra um para ver as tentativas, a resposta da sua ferramenta e o conteúdo exato que foi enviado.
- Enviar novamente: reenvia um aviso que falhou, por exemplo depois de corrigir a sua ferramenta.
Se um envio falhar, o TrainerStudio volta a tentar sozinho até 8 vezes durante pouco mais de um dia, esperando mais de cada vez. Não tem de fazer nada.
6. Gire o segredo se o perder
Na página do endpoint, clique em Girar segredo. Recebe um segredo novo e, durante 24 horas, os avisos são assinados com o novo e com o anterior: tem esse tempo para o mudar na sua ferramenta sem perder avisos.
7. Desative ou elimine um endpoint
- Desativar deixa de enviar avisos para esse endpoint e cancela os pendentes. Pode Ativar de novo quando quiser. Os eventos que ocorrerem enquanto está desativado não são enviados depois.
- Excluir endpoint elimina-o de vez. Não é possível desfazer.
Se o TrainerStudio o desativar sozinho
Um endpoint é desativado automaticamente quando:
- está há 3 dias sem aceitar nenhum envio, ou
- a sua ferramenta responde que esse endereço já não existe.
Verá um aviso com o motivo na página do endpoint. Resolva o problema na sua ferramenta e clique em Reativar.
O que convém saber
- Trate o URL e o segredo como uma palavra-passe. Não os partilhe nem os publique.
- Um endpoint por ferramenta, com uma descrição clara.
- O mesmo aviso pode chegar duas vezes se tiver havido uma nova tentativa. As ferramentas robustas contam com isso; tenha-o presente se usar uma automatização simples.
- Os avisos podem chegar fora de ordem. Cada um indica a hora em que o evento aconteceu.
- Só quer falar com os seus dados a partir do ChatGPT ou do Claude? Não precisa de webhooks: siga os guias específicos.