Receba eventos com webhooks
Antes de começar
Planeje a recepção de eventos, a verificação da origem e o tratamento de entregas repetidas.
- Endpoint HTTPS controlado pelos participantes do projeto e acesso autorizado à API.
- Armazenamento para registrar eventos processados.
Um webhook informa que algo aconteceu no Workspace. A integração ainda precisa conferir a origem do evento e definir o que fazer com ele.
Escolha o evento e o local
No cadastro pela API, selecione os eventos necessários e o destino HTTPS. Restrinja o local acompanhado à atividade do projeto. O webhook está ligado à identidade autenticada que o criou, portanto mudanças nesse perfil podem afetar a entrega dos eventos.
Confira a origem
Guarde o segredo devolvido no cadastro para validar a assinatura das chamadas recebidas.
A assinatura chega no cabeçalho X-Signature. Seu cálculo usa HMAC-SHA256 com o segredo do webhook. Compare o resultado calculado sobre o corpo recebido com a assinatura informada. O segredo pertence ao webhook e deve ficar no armazenamento de credenciais da integração.
Preservar o corpo original evita diferenças introduzidas pela leitura e reconstrução do JSON. Faça um teste com o evento original e outro com o corpo alterado. A segunda chamada deve ser recusada pela validação antes de provocar escrita no ClickUp.
Separe recebimento e alteração da tarefa
O evento informa uma mudança, enquanto o seu código define a ação seguinte. Por exemplo, ao receber uma atualização de tarefa, a integração pode consultar o registro atual antes de preparar um aviso. Compare o status consultado com o evento recebido antes de escrever o aviso.
Registre o nome do evento, o identificador da tarefa e o resultado do processamento. O evento taskUpdated exige leitura diferente de taskCreated. Não trate toda chamada recebida como autorização para criar uma nova tarefa ou registrar um comentário.
Evite processamento duplicado
Registre os identificadores disponíveis no evento e o resultado do processamento. Antes de aplicar uma ação, confira se o mesmo evento já foi tratado. Para operações de escrita, defina como consultar o estado atual e recuperar uma falha parcial.
Para verificar duplicidade, envie o mesmo evento de teste duas vezes e observe quantas ações foram produzidas. Se houver dois comentários idênticos, falta uma proteção no processamento. A confirmação HTTP ao emissor e a conclusão da alteração precisam ser acompanhadas separadamente.
Use tarefas de estudo para esses testes. A recepção HTTP confirma apenas a chegada da chamada. Consulte o recurso final e acompanhe os registros da integração.
Confira o resultado
O receptor distingue um evento válido, uma assinatura inválida e a repetição de um evento já tratado.
Fontes e conferência
Procedimento conferido na documentação indicada. Não executado em um Workspace de laboratório. A disponibilidade e os nomes da interface podem variar conforme o plano, a função e a versão.