Você está tentando registrar um novo webhook em uma integração do Notion, mas vê a mensagem de erro “Webhook Cannot Be Registered.” Esse erro significa que a integração atingiu o número máximo permitido de assinaturas de webhook ativas. O Notion impõe um limite estrito de quantos webhooks uma única integração interna ou pública pode manter de uma vez. Este artigo explica o limite exato, por que o erro ocorre e as etapas para resolvê-lo removendo webhooks não usados ou atualizando seu plano de integração.
Principais Conclusões: Corrigindo o Limite de Registro de Webhook em Integrações do Notion
- Capacidades da Integração > Assinaturas de Webhook: O Notion limita as integrações a 3.000 assinaturas de webhook ativas para planos Plus e Business, e 1.500 para planos Gratuitos.
- API do Notion > Endpoint List Webhooks: Use o endpoint GET /webhooks para recuperar todos os webhooks registrados e identificar quais não são mais necessários.
- API do Notion > Endpoint Delete Webhook: Use o endpoint DELETE /webhooks/{webhookId} para remover webhooks obsoletos e liberar capacidade.
Por que o Notion Bloqueia o Registro de Novos Webhooks
O Notion usa um limite de assinatura de webhook por integração para evitar abusos e garantir a estabilidade da API. Cada integração, seja interna ou pública, pode registrar um número máximo de webhooks. O limite depende do plano do workspace:
- Workspace do plano Gratuito: 1.500 webhooks ativos por integração
- Workspaces dos planos Plus, Business e Enterprise: 3.000 webhooks ativos por integração
Uma assinatura de webhook é contada como ativa desde o momento em que é criada até ser explicitamente excluída via API. Webhooks excluídos ou expirados não contam para o limite. O erro “Webhook Cannot Be Registered” aparece quando a integração já possui o número máximo de assinaturas ativas. Isso pode acontecer se sua automação cria webhooks dinamicamente, mas nunca os limpa, ou se vários desenvolvedores compartilham o mesmo token de integração e registram webhooks sem coordenação.
Etapas para Resolver o Erro de Limite de Registro de Webhook
- Identifique seu plano do workspace
Vá em Configurações e Membros > Configurações > Configurações do Workspace. Veja o nome do plano no topo da página. Se você está no plano Gratuito, o limite é de 1.500 webhooks por integração. No Plus ou Business, o limite é de 3.000. - Liste todos os webhooks registrados para a integração
Envie uma requisição GET para o endpoint da API do Notionhttps://api.notion.com/v1/webhooks. Inclua o token de integração no cabeçalho Authorization. A resposta retorna um array de objetos webhook com seus IDs, URLs e status. Exemplo usando cURL:curl -X GET 'https://api.notion.com/v1/webhooks' -H 'Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO' -H 'Notion-Version: 2022-06-28' - Revise a lista de webhooks em busca de assinaturas não utilizadas
Compare cada URL de webhook com seus fluxos de automação atuais. Qualquer webhook apontando para um endpoint desativado, um servidor de teste ou um serviço que não está mais em execução deve ser removido. Procure também por webhooks duplicados que assinam o mesmo evento e página. - Exclua webhooks obsoletos
Para cada webhook que deseja remover, envie uma requisição DELETE parahttps://api.notion.com/v1/webhooks/{webhookId}. Substitua {webhookId} pelo ID real da lista. Exemplo:curl -X DELETE 'https://api.notion.com/v1/webhooks/abc123-def456' -H 'Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO' -H 'Notion-Version: 2022-06-28'
Após a exclusão, o webhook não conta mais para o limite. Repita para todos os webhooks não utilizados. - Tente registrar o novo webhook novamente
Envie uma requisição POST parahttps://api.notion.com/v1/webhookscom o corpo JSON necessário, incluindo a URL de destino, array de eventos e filtro opcional. Se o total de webhooks ativos agora estiver abaixo do limite, o registro será bem-sucedido.
Se o Notion Ainda Recusar Registrar o Webhook
Limite de webhook ainda excedido após excluir webhooks
Se você excluiu webhooks, mas ainda recebe o erro, verifique se as exclusões foram concluídas com sucesso. O endpoint DELETE retorna uma resposta 200 OK com corpo vazio. Se você recebeu um erro 404 ou 400, o ID do webhook pode estar incorreto ou a exclusão falhou. Execute o comando de listagem novamente para confirmar que o total diminuiu. Observe também que webhooks excluídos podem levar até 60 segundos para serem removidos da contagem do limite em alguns casos. Aguarde um minuto e tente novamente.
Várias integrações compartilham o mesmo token
Se sua equipe usa o mesmo token de integração em diferentes serviços, cada serviço pode registrar webhooks independentemente, ultrapassando o limite. Crie uma integração interna separada para cada serviço de automação distinto. Cada integração tem seu próprio limite de webhooks. Acesse https://www.notion.so/my-integrations e crie uma nova integração para o serviço que precisa do webhook.
Webhooks criados por páginas excluídas ainda contam
Quando uma página à qual um webhook assina é excluída, a assinatura do webhook em si permanece ativa no sistema do Notion. Esses webhooks órfãos ainda contam para o limite. Você deve excluí-los manualmente usando o endpoint DELETE, conforme mostrado acima. Não há limpeza automática para webhooks em páginas excluídas.
Comparação dos Limites de Webhook por Plano do Notion
| Item | Plano Gratuito | Plus / Business / Enterprise |
|---|---|---|
| Máximo de webhooks por integração | 1.500 | 3.000 |
| Retenção de webhook após exclusão de página | Webhook permanece ativo até ser excluído manualmente | Webhook permanece ativo até ser excluído manualmente |
| Limite de taxa da API por integração | 3 requisições por segundo | 3 requisições por segundo (limites maiores disponíveis no Enterprise) |
| Tipos de eventos de webhook suportados | Todos (page_updated, page_created, etc.) | Todos |
Se você precisa consistentemente de mais de 3.000 webhooks, considere reestruturar sua automação para usar menos webhooks, assinando páginas pai ou usando eventos de nível de banco de dados em vez de eventos de página individuais. Para workspaces Enterprise, entre em contato com seu representante do Notion para solicitar um limite maior de webhooks.
Agora você pode identificar e remover assinaturas de webhook não utilizadas para liberar capacidade para novos registros. Em seguida, configure um script recorrente que seja executado semanalmente usando os endpoints List Webhooks e Delete Webhook para limpar automaticamente webhooks órfãos. Como dica avançada, use a propriedade filter ao criar webhooks para assinar apenas páginas específicas de banco de dados, o que reduz o número total de webhooks necessários para monitoramento granular.