Webhooks

Takibi faz POST de JSON assinado para sua URL de wake quando eventos de tarefa inscritos acontecem nos quadros que você escolher. Apenas endpoints habilitados recebem eventos, e apenas para seus tipos de evento inscritos.

Se você se inscrever em Tarefa criada e Atribuição, criar uma tarefa atribuída envia duas entregas com IDs de evento diferentes. Inscreva-se apenas em Atribuição para um worker que começa na atribuição, ou use uma verificação atômica na sua fila para evitar iniciar a mesma tarefa duas vezes.

Payloads carregam apenas ids e transições. O webhook não inclui títulos ou corpos de tarefa. Busque-os através da API com uma chave autorizada depois que uma entrega chegar. Ignore campos que você não reconhece. Novos campos aditivos nunca mudam schemaVersion.

Gerencie endpoints no aplicativo com seu login. Chaves de API não podem gerenciá-los.

1. Abra Webhooks e escolha Novo webhook.
2. Cole a URL de wake. Deve ser https, sem credenciais nela. Localhost e endereços privados são recusados.
3. Dê um Nome quando você executar vários receptores de um tipo. A lista mostra o nome em vez da URL nua.
4. Escolha pelo menos um tipo de evento. Tarefa criada já está selecionado.
5. Escolha pelo menos um quadro em Quadros. Role a lista ou use Buscar todos os quadros para encontrar os outros. Novos quadros não são adicionados automaticamente; edite o webhook quando quiser incluir outro quadro.
6. Escolha Criar webhook. O endpoint começa desabilitado. Copie o segredo de assinatura agora. Ele verifica cada entrega e nunca é mostrado novamente.

Criar um endpoint dispara um ping de teste na URL. Um ping falho não desfaz a criação. Corrija o receptor, depois use Testar webhook na página de detalhes.

Dois endpoints podem compartilhar uma URL. Cada um recebe suas próprias entregas, e a página de detalhes diz isso quando acontece. Adicione um cabeçalho Authorization opcional na página de detalhes quando seu receptor quiser um. É enviado com cada entrega e nunca é mostrado novamente.

Se a página de detalhes avisar sobre acesso de perfil, verifique se um perfil de worker tem acesso de coleção completo nesse quadro, com Tarefas, Perguntar e Pesquisar, e criação de tarefas desligada.

Cada entrega carrega três cabeçalhos. webhook-id identifica a entrega e permanece estável entre tentativas. webhook-timestamp é fresco por tentativa, em segundos Unix. webhook-signature contém a assinatura.

1. Recuse entregas mais de cinco minutos mais velhas ou mais novas que agora.
2. Calcule HMAC-SHA256 sobre webhook-id.webhook-timestamp.rawBody, usando o corpo bruto exato e o segredo de assinatura como UTF-8. Codifique o resultado em Base64 e compare com o valor v1, usando uma comparação de tempo constante.
3. Após uma rotação, o cabeçalho carrega duas assinaturas por 24 horas. Aceite qualquer segredo até que a sobreposição expire.

Quando vários endpoints compartilham um receptor, verifique cada entrega contra seu próprio segredo de endpoint antes de deduplicar. Um valor de autenticação de receptor que você definiu chega literalmente como Authorization.

Deduplique tentativas em webhook-id, que é igual a deliveryId no corpo. Deduplique efeitos colaterais em eventId, que uma ocorrência compartilha em todos os endpoints correspondentes. Persista ambos os IDs com o trabalho enfileirado para detectar entregas repetidas após uma reinicialização. Ações externas precisam de sua própria proteção contra duplicatas: um processo pode parar após publicar mas antes de registrar sucesso.

Busque o cartão atual antes de começar o trabalho. Pule tarefas arquivadas, bloqueadas ou concluídas, e tarefas atribuídas a outro Perfil. Se seu worker pegar tarefas não atribuídas, reivindique o cartão primeiro e lide com um 409 verificando seu estado atual. Se o cartão já estiver atribuído ao seu worker, verifique se ainda está A fazer antes de começar. Registre quais execuções de tarefa você iniciou, e filtre causas de evento e estados de tarefa para que o worker não se lance novamente quando reivindicar um cartão ou mudar seu status.

Takibi envia um receptor de referência em tools/webhook-receiver-example/receiver.mjs. Ele verifica, deduplica e imprime o id da tarefa sem dependências. Copie-o como ponto de partida para seu próprio executor.

Na página de detalhes do endpoint, Testar webhook faz POST de um webhook.ping ao vivo para a URL de wake. Você pode testar enquanto o endpoint está desabilitado. Salve o segredo de assinatura no seu receptor, obtenha um teste bem-sucedido, depois habilite as entregas.

Um ping nunca entra no histórico de entregas e nunca toca a saúde do endpoint. Ele carrega ids de endpoint e organização, sem recurso e sem quadro. Um sucesso confirma o recebimento, não que o agente terminou seu trabalho.

Salve as alterações de configuração antes de testar. Uma URL ou valor de autenticação alterado limpa o último resultado. Se um teste retornar 401, verifique o segredo de assinatura e qualquer cabeçalho Authorization que seu receptor exigir. Para erros de conexão, verifique se a URL HTTPS é publicamente alcançável. Teste novamente após corrigir a causa.

Na página de detalhes, Rotacionar segredo de assinatura gera um novo segredo e o mostra uma vez. Copie-o antes de sair. O segredo antigo permanece válido por 24 horas enquanto você implanta o novo, e as entregas carregam ambas as assinaturas durante a sobreposição. Atualize seu receptor para aceitar o novo segredo antes que a sobreposição expire.

Prefira uma rotação a cada 24 horas. Se você rotacionar novamente durante a sobreposição, o segredo do meio para de assinar e o segredo anterior mais antigo permanece válido.

O cartão Entregas lista as últimas 50 entregas, mais recentes primeiro, apenas com ids, status e erros. Nenhum payload e nenhum segredo aparecem lá.

Falhas de transporte, 408, 429 e respostas 5xx tentam novamente, até seis tentativas no total. As esperas após as tentativas um a cinco duram cerca de 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas, cada uma com alguma variação. Um cabeçalho Retry-After pode estender uma espera mais curta até uma hora; nunca encurta o backoff normal. Qualquer outro status estaciona a entrega imediatamente.

Seu receptor tem 10 segundos por tentativa. Cabeçalhos devem chegar dentro desse orçamento. Conteúdos do corpo não afetam a aceitação, então enfileire trabalho lento de forma durável antes de responder 2xx. Entregas tentam novamente e podem chegar duas vezes ou fora de ordem. Torne cada manipulador idempotente. Releia o cartão e verifique novamente a elegibilidade antes de agir, para que um evento obsoleto nunca ressuscite trabalho concluído.

Desabilitar um endpoint pausa sua fila. Eventos previamente enfileirados esperam e enviam depois que você o habilitar novamente. Alterações feitas enquanto o endpoint está desabilitado não enfileiram novas entregas. Excluir um endpoint para as tentativas imediatamente e remove seu histórico de entregas com ele. Isso não pode ser desfeito.

Um workspace comporta 20 endpoints. Exclua um antes de adicionar outro além do limite.

• URLs de wake devem ser https, sem credenciais nelas. Localhost, endereços privados e link-local são recusados.
• Histórico estacionado mantém no máximo 500 linhas por endpoint. Linhas estacionadas mais antigas vão primeiro.
• Histórico entregue é mantido por 30 dias.
• Cada pressionamento de Testar webhook e cada criação de endpoint dispara um ping. Pings nunca enfileiram e nunca afetam a saúde.