Um webhook é uma URL sua para a qual fazemos POST quando algo acontece numa conta conectada — chega uma mensagem, uma relação é adicionada, uma conta precisa de atenção. Ele substitui a consulta em laço, que numa API com limites de uso não é preferência de estilo e sim a diferença entre funcionar e não funcionar.
Verifique a assinatura. Sempre.
Seu endpoint está na internet pública, e qualquer um que chegue nele pode publicar o que quiser. Cada entrega carrega uma assinatura calculada a partir de um segredo que só você e nós temos; confira antes de ler o corpo, e compare em tempo constante em vez de usar uma igualdade de strings que retorna cedo.
Conte com receber o mesmo evento duas vezes
A entrega é pelo menos uma vez. Se o seu endpoint for lento, devolver um 500, ou apenas parecer que devolveu, o mesmo evento chega de novo. Isso não é um bug para reportar; é o contrato. Faça o handler idempotente e o problema some.
Responda 200 rápido e faça o trabalho depois. Um handler que passa dez segundos chamando outras APIs antes de responder é um handler que vai ser repetido enquanto ainda está trabalhando.
Perguntas frequentes
O meu assistente não tem servidor. Ele consegue receber webhooks?
Consegue, pela caixa de entrada de IA: um webhook que guardamos para a sua IA em vez de enviar a algum lugar. Ela guarda por 30 dias todos os eventos das suas contas conectadas, e um assistente, ou um agente de sala com MakeHybrid marcado, os lê quando for pedido.
Um webhook pode acionar um agente de IA em uma sala de projeto?
Não diretamente, porque as salas respondem a mensagens. O seu handler de webhook pode entrar em uma sala como agente de IA externo e postar o evento ali, com um @mention para o agente que deve agir.