Ves el error ‘Webhook Token Invalid’ cuando tu bot o integración de Discord intenta enviar un mensaje a un canal. Esto sucede porque el token del webhook ha sido cambiado por Discord o por una rotación manual. Discord rota los tokens de webhook automáticamente bajo ciertas condiciones, y el token antiguo deja de funcionar de inmediato. Este artículo explica por qué el token se vuelve inválido y proporciona instrucciones paso a paso para rotar y actualizar tus tokens de webhook.
Puntos clave: Solucionar el error ‘Webhook Token Invalid’
- Canal > Integraciones > Webhooks > Copiar URL del webhook: Obtén la URL y el token del webhook válidos actuales directamente desde Discord.
- Configuración del servidor > Integraciones > Webhooks > Editar > Regenerar: Rota manualmente el token del webhook cuando sospeches que está comprometido o desactualizado.
- Actualiza el código de tu bot o la configuración de la integración: Reemplaza el token antiguo en tu aplicación o servicio de terceros con el nuevo.
Por qué el token del webhook se vuelve inválido
Un webhook de Discord consta de dos partes: un ID numérico y un token secreto. El token es una cadena larga de caracteres que autentica el webhook al enviar mensajes. Si el token cambia, cualquier aplicación que use el token antiguo recibe el error ‘Webhook Token Invalid’.
Discord rota automáticamente el token del webhook cuando ocurre cualquiera de estos eventos:
- Un administrador del servidor regenera manualmente el token desde la página de configuración del webhook.
- El webhook es eliminado y recreado por un administrador o bot.
- Discord realiza una rotación de seguridad en su backend, aunque esto es poco frecuente.
- Una integración o bot usa el webhook con un token desactualizado después de una acción de moderación del servidor.
El mensaje de error no especifica qué campo es inválido. Solo dice ‘Webhook Token Invalid’, lo que significa que la parte del token en la URL no coincide con lo que Discord espera. El ID del webhook en sí rara vez cambia, pero el token es la parte sensible que debe permanecer secreta.
Pasos para rotar y actualizar el token del webhook
Debes tener el permiso Gestionar webhooks en el servidor de Discord para realizar estos pasos. Si no eres administrador o moderador del servidor, contacta al propietario del servidor.
- Abre el canal donde se usa el webhook
Navega al canal de texto que recibe mensajes del webhook. Haz clic derecho en el nombre del canal o haz clic en el ícono de engranaje junto a él para abrir la Configuración del canal. - Ve a Integraciones > Webhooks
En la barra lateral izquierda, haz clic en Integraciones. En Webhooks, verás una lista de todos los webhooks creados para ese canal. Haz clic en el webhook que está produciendo el error. - Copia la URL actual del webhook
Haz clic en el botón Copiar URL del webhook. Esto copia la URL completa, incluido el nuevo token. Pega esta URL en un archivo de texto o gestor de contraseñas para usarla más tarde. - Regenera el token manualmente si es necesario
Si sospechas que el token fue comprometido, haz clic en el botón Regenerar debajo del nombre del webhook. Aparece un cuadro de diálogo de confirmación. Haz clic en Regenerar para confirmar. El token antiguo deja de funcionar de inmediato. Copia la nueva URL del webhook después de la regeneración. - Actualiza el código de tu bot o la integración de terceros
Abre tu aplicación que envía mensajes a través del webhook. Reemplaza la URL antigua del webhook con la nueva. Si usas un servicio de terceros como GitHub, Zapier o IFTTT, ve a la configuración de ese servicio y actualiza la URL del webhook. - Prueba el webhook
Envía un mensaje de prueba desde tu aplicación o usa el probador de webhooks de Discord en la configuración del webhook. Haz clic en el botón Probar webhook en Discord para verificar que el nuevo token funciona. Si el mensaje aparece en el canal, la rotación fue exitosa.
Si el webhook fue eliminado
Si el webhook fue eliminado por completo, no puedes recuperar el ID ni el token antiguos. Debes crear un nuevo webhook desde cero. Ve a Configuración del canal > Integraciones > Webhooks > Crear webhook. Dale un nombre y un avatar, luego copia la nueva URL. Actualiza tu aplicación con esta nueva URL.
Si no tienes el permiso Gestionar webhooks
Contacta a un administrador o moderador del servidor que tenga el permiso Gestionar webhooks. Ellos pueden realizar los pasos anteriores y proporcionarte la nueva URL del webhook. No pidas que el token se envíe por mensaje directo; pídeles que lo peguen en un canal privado que solo tú puedas ver.
Si el error persiste después de la rotación del token
La URL del webhook contiene caracteres adicionales
Al copiar la URL del webhook, asegúrate de copiar la cadena completa. Algunas aplicaciones truncan accidentalmente la URL o agregan espacios en blanco. Pega la URL en un editor de texto sin formato y verifica que coincida con lo que muestra Discord. El formato de la URL es: https://discord.com/api/webhooks/ID/TOKEN
El bot usa un token en caché desactualizado
Si tu bot almacena en caché la URL del webhook en memoria o en un archivo de configuración, es posible que aún use el token antiguo. Reinicia el bot y borra cualquier dato en caché. Revisa el archivo de configuración de tu bot en busca de URL de webhook codificadas y actualízalas.
El servicio de terceros tiene un retraso
Algunos servicios de terceros almacenan en caché las URL de webhook durante varios minutos. Después de actualizar la URL, espera hasta cinco minutos e inténtalo de nuevo. Si el error continúa, elimina el webhook del servicio y agrégalo de nuevo con la nueva URL.
El ID del webhook cambió
Rara vez, el ID completo del webhook cambia si el webhook fue eliminado y recreado. Verifica que el ID en tu aplicación coincida con el ID en la configuración del webhook de Discord. El ID es la parte numérica de la URL entre /webhooks/ y el token.
Métodos de actualización del token del webhook: manual vs programático
| Elemento | Rotación manual a través de la interfaz de Discord | Rotación programática a través de la API |
|---|---|---|
| Permiso necesario | Gestionar webhooks en el servidor | Gestionar webhooks en el servidor y un token de bot con los alcances adecuados |
| Pasos | Abrir la configuración del canal, regenerar el token, copiar la URL | Enviar una solicitud PATCH a /webhooks/ID con el nuevo parámetro token |
| Velocidad | Inmediata, requiere copiar y pegar manualmente | Inmediata, se puede automatizar en el código |
| Riesgo de error | Bajo, ya que ves la nueva URL directamente | Medio, requiere el endpoint de API correcto y autenticación |
| Ideal para | Un solo webhook o actualizaciones ocasionales | Múltiples webhooks o rotaciones frecuentes en producción |
El método manual se recomienda para la mayoría de los usuarios porque es simple y no requiere programación. El método programático es útil para desarrolladores de bots que necesitan rotar tokens para muchos webhooks a la vez.
El error ‘Webhook Token Invalid’ se soluciona obteniendo el token actual de Discord y actualizando tu aplicación. Copia siempre la URL completa del webhook desde la interfaz de Discord para evitar errores tipográficos. Para sistemas automatizados, considera almacenar la URL del webhook en una variable de entorno segura y actualizarla programáticamente cuando Discord rote el token. Si el error continúa, revisa si hay datos en caché en tu aplicación o servicio de terceros.