Esta página é uma tradução automática da página em inglês, que é a versão de referência. Ler a página em inglês
Webhooks do servidor
Os webhooks enviam denúncias, pedidos de cadastro, criações de contas e mudanças de perfil, ações de moderação, recursos, ações de domínio, publicações públicas locais e ações de gerenciamento de emojis personalizados para um relay do Slack ou do Discord, um sistema de chamados ou uma ferramenta de automação como o n8n. Um servidor sem webhooks configurados não guarda linhas extras nem roda jobs extras. O que um receptor recebe (cabeçalhos, assinatura, eventos e corpo) está descrito na referência de webhooks.
Configurar um webhook
Seção intitulada “Configurar um webhook”Quem tem a permissão manage_webhooks pode configurar webhooks na tela de administração “Webhooks” (/admin/webhooks).
O papel admin embutido a tem. “Configurar um webhook” abre o formulário; escolher um webhook na lista abre a página dele, onde
você o testa, o desativa e ativa, o altera, vê as entregas dos últimos 14 dias e reenvia uma, dá a ele um novo
segredo e o exclui depois de digitar o nome do host da URL dele. A página informa quando as entregas continuam falhando e quando o
servidor desativou o webhook. O histórico mostra o evento, o status, as tentativas e a última tentativa de cada entrega, e o corpo
que ela enviou, que pode conter dados pessoais e só é exibido a quem também tem a permissão que o evento exige (veja abaixo).
- Crie um webhook com uma URL de destino, uma descrição e os eventos a assinar. Cada evento também exige a sua própria
permissão além de
manage_webhooks:manage_reportspara denúncias,manage_accountspara cadastros, contas, ações de moderação e contestações,manage_domainspara ações sobre domínios,manage_custom_emojispara emoji personalizados emanage_errorspara grupos de erros. Publicações públicas não exigem permissão extra. Você não pode selecionar um evento cuja permissão você não tem. - O segredo (
whsec_...) é mostrado uma vez, quando o webhook é criado. Configure-o no receptor. Ele não pode ser mostrado de novo. - Na página do webhook, escolha “Enviar um teste” para enviar
webhook.teste confira nas entregas dele que chegou.
Criar, alterar, excluir, ativar, desativar e trocar o segredo de um webhook ficam registrados no log de auditoria. O alvo é mostrado como a descrição e o nome do host da URL; a URL em si não é registrada.
Trocar o segredo
Seção intitulada “Trocar o segredo”“Gerar um novo segredo” cria um novo segredo e o mostra uma vez. Nas 24 horas seguintes as mensagens também são assinadas com o segredo antigo
(webhook-signature traz duas assinaturas), então você pode mudar o receptor para o novo segredo nessa janela.
Os segredos são selados com kernel.Sealer antes de serem gravados no banco de dados; a chave é a
KEK.
Falhas e reenvio
Seção intitulada “Falhas e reenvio”- Se o destino responder com qualquer coisa diferente de
2xx, não responder em até 15 segundos, ou não puder ser alcançado, a mensagem é tentada de novo após 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas e mais 10 horas (8 tentativas no total, cerca de 27 horas). Uma entrega que usou todas se torna um job morto, e “Enviar de novo” nas entregas a envia outra vez com o mesmowebhook-id. - Se o destino responder
410 Gone, o webhook é desativado imediatamente. - O servidor desativa um destino que não teve sucesso por 72 horas desde a primeira falha e que falhou 20 vezes ou mais seguidas. O registro de auditoria ganha uma entrada
webhook_disabledporsystem, e todas as pessoas commanage_webhooksrecebem uma notificação no aplicativo (e um e-mail, se escolheram receber notificações por e-mail). - A lista na tela de administração mostra o número de falhas seguidas e o motivo pelo qual o servidor desativou um webhook (
goneoufailing). Ative o webhook de novo depois de corrigir o destino. As mensagens de quando ele estava desativado não são enviadas de novo. - As mensagens e as entregas são excluídas após 14 dias (fixo). Os corpos contêm dados pessoais, como o comentário de uma denúncia.
Destinos em uma rede interna
Seção intitulada “Destinos em uma rede interna”A entrega passa pela proteção SSRF do HTTP de saída. Por padrão, ela só alcança endereços públicos por https (portas 443
e 80). Para enviar a um destino interno, como um n8n no mesmo host ou um chat dentro da sua VPC, liste nomes de host,
endereços IP e CIDRs, separados por vírgulas, na configuração webhook_allowed_destinations (variável de ambiente
MY_WEBHOOK_ALLOWED_DESTINATIONS; veja a referência de configuração).
MY_WEBHOOK_ALLOWED_DESTINATIONS=n8n.internal,10.0.0.0/8- Somente os destinos listados, e somente para a entrega de webhooks, ficam isentos da proteção. Federação, mídia e pré-visualizações de links não mudam. Um destino isento também pode usar
httpe qualquer porta. - Um nome de host é permitido qualquer que seja o endereço em que ele resolve. Um CIDR é permitido quando a URL informa um endereço IP nessa faixa. Se você usar um nome de host que resolve para dentro da faixa, liste também o nome de host.
- Somente um operador com acesso ao servidor pode alterar a configuração. As permissões da tela de administração, sozinhas, não alcançam uma rede interna.
- Uma tentativa a um destino que a proteção recusou mostra
forbidden_destinationnas entregas. - A configuração de desenvolvimento
http_allow_private_networksremove a proteção para todas as finalidades, inclusive os webhooks.
Para LLMs e agentes de programação:llms.txt,llms-full.txt, llms-small.txt