Recibes un error “Discord Webhook Delivery Failed With 401” cuando tu sistema automatizado intenta enviar un mensaje a un canal de Discord. Este código de estado 401 significa que la solicitud no estaba autorizada. Discord rechazó el webhook porque el token de autenticación faltaba, no era válido o había expirado. Este artículo explica las tres causas principales de este error y cómo resolver cada una.
Puntos clave: Cómo solucionar el error 401 del webhook
- Discrepancia en el token de la URL del webhook: El token de tu solicitud no coincide con el token que Discord emitió para ese webhook.
- Webhook expirado o eliminado: El webhook se eliminó del canal o el token expiró debido a un cambio en la configuración del servidor.
- Método HTTP o endpoint incorrecto: Usar una solicitud POST a la URL incorrecta o usar una solicitud GET en lugar de POST.
Por qué Discord devuelve un error 401 para webhooks
Una URL de webhook de Discord contiene un ID único y un token. La estructura es https://discord.com/api/webhooks/<webhook_id>/<webhook_token>. Cuando tu aplicación envía una solicitud POST a esta URL, Discord verifica que el token coincida con el token almacenado para ese ID de webhook. Si el token es incorrecto, falta o el webhook ya no existe, Discord devuelve HTTP 401 Unauthorized.
El error 401 no es un problema de red ni del servidor. Es un fallo de autenticación. Discord no devuelve 401 por limitación de velocidad ni por límites de tamaño de carga útil. Esos devuelven 429 o 413. El error 401 siempre apunta a un problema de credenciales.
Causa 1: El token del webhook no coincide con el ID
La causa más común es un error de copiar y pegar. Cuando creas un webhook en Server Settings > Integrations > Webhooks, Discord genera una URL. Si editas manualmente esta URL, podrías cambiar un carácter del token. El token distingue entre mayúsculas y minúsculas. Un solo carácter incorrecto provoca un 401.
Causa 2: El webhook se eliminó o se regeneró
Si alguien con permiso Manage Webhooks elimina el webhook, la URL deja de ser válida. Cualquier solicitud POST a esa URL devuelve 401. De manera similar, si un moderador regenera el token del webhook, el token antiguo deja de funcionar. El ID del webhook sigue siendo el mismo, pero el nuevo token reemplaza al anterior.
Causa 3: Método HTTP o endpoint incorrecto
Los webhooks de Discord solo aceptan solicitudes POST. Enviar una solicitud GET a la URL del webhook devuelve 401. Además, usar el endpoint de API incorrecto, como /api/webhooks/<id> sin el token, provoca un 401. El endpoint completo debe incluir tanto el ID como el token.
Pasos para diagnosticar y solucionar el error 401 del webhook
Paso 1: Verificar la URL del webhook en Discord
- Abrir Server Settings
Haz clic derecho en el nombre del servidor en la lista de canales. Selecciona Server Settings en el menú contextual. - Ir a Integrations
En la barra lateral izquierda, haz clic en Integrations. En Webhooks, haz clic en el webhook que está fallando. - Copiar la URL del webhook
Haz clic en Copy Webhook URL. No edites esta URL. Pégala directamente en la configuración de tu aplicación.
Paso 2: Comprobar si el token se regeneró
- Abrir los detalles del webhook
Sigue el Paso 1 para abrir la página del webhook en Integrations. - Buscar la advertencia de token regenerado
Si alguien hizo clic en Regenerate, Discord muestra una advertencia: “The webhook URL has been regenerated. The old URL will no longer work.” Actualiza tu aplicación con la nueva URL.
Paso 3: Probar el webhook con cURL
- Abrir una terminal
En Windows, presiona Win+R, escribecmdy presiona Enter. En macOS o Linux, abre Terminal. - Ejecutar el comando cURL
Escribe:curl -X POST -H "Content-Type: application/json" -d '{"content":"test"}' YOUR_WEBHOOK_URL. Reemplaza YOUR_WEBHOOK_URL con la URL exacta de Discord. Si obtienes un 401, la URL es incorrecta o el webhook está eliminado.
Paso 4: Confirmar que el webhook existe
- Revisar la lista de webhooks
En Server Settings > Integrations, desplázate hasta la sección Webhooks. Si el webhook no aparece, alguien lo eliminó. Crea un nuevo webhook. - Crear un nuevo webhook
Haz clic en Create Webhook. Asígnale un nombre y un canal. Haz clic en Copy Webhook URL. Usa esta nueva URL en tu aplicación.
Paso 5: Asegurarte de que usas POST
- Revisar el código de tu aplicación
Busca el método HTTP en tu script. Debe ser POST. Si usas GET, PUT o DELETE, Discord devuelve 401. - Revisar la URL del endpoint
Asegúrate de que la URL termine con/api/webhooks/<id>/<token>. No agregues segmentos de ruta adicionales como/slacko/githuba menos que uses el endpoint compatible con Slack de Discord. Ese endpoint es/api/webhooks/<id>/<token>/slacky también requiere el token.
Si Discord sigue devolviendo 401 después de la solución principal
La URL del webhook contiene saltos de línea o espacios
Al copiar la URL del webhook desde Discord, el navegador podría agregar un salto de línea final. Este carácter adicional rompe el token. Pega la URL en un editor de texto sin formato como Notepad. Elimina cualquier espacio o salto de línea antes de guardar la URL en la configuración de tu aplicación.
La aplicación almacena en caché la URL antigua del webhook
Algunas aplicaciones almacenan en caché los valores de configuración. Después de actualizar la URL del webhook, reinicia la aplicación o borra la caché. Por ejemplo, en un bot de Discord que usa discord.py, reinicia el proceso del bot. En una canalización de CI/CD como GitHub Actions, envía una nueva confirmación para activar una compilación nueva.
El nivel de boost del servidor afecta los límites de webhooks
Discord limita la cantidad de webhooks por canal según el nivel de boost del servidor. Si tu servidor tiene menos de 10 webhooks por canal, esto no es un problema. Superar el límite no causa un error 401. Hace que Discord rechace la creación del webhook, no la entrega. Si no puedes crear un nuevo webhook, revisa el límite de webhooks del canal en Server Settings > Integrations.
Métodos de autenticación de webhooks de Discord: token vs OAuth2
| Elemento | Token de webhook | Token de bot OAuth2 |
|---|---|---|
| Tipo de autenticación | Token en la ruta de la URL | Token Bearer en el encabezado Authorization |
| Alcance del acceso | Solo un canal | Todos los canales a los que el bot tiene acceso |
| Rotación de tokens | Regeneración manual en la interfaz | Automática a través del Discord Developer Portal |
| Error con token no válido | HTTP 401 Unauthorized | HTTP 401 Unauthorized con código de error 50001 |
| Caso de uso | Publicación simple de mensajes desde servicios externos | Interacción completa del bot con comandos e incrustaciones |
Los webhooks de Discord usan un token simple incrustado en la URL. Este token no expira a menos que se regenere. Los tokens de bot OAuth2 requieren un ID de cliente y un secreto, y se pueden revocar desde el portal de desarrolladores. Para la entrega simple de mensajes, los webhooks son más fáciles de configurar. Para funciones interactivas, usa un bot.
Para resolver un error 401, comienza copiando la URL del webhook directamente desde Server Settings > Integrations. Pruébala con cURL usando una solicitud POST. Si la prueba tiene éxito, actualiza la configuración de tu aplicación. Si la prueba falla, el webhook se eliminó o el token se regeneró. Crea un nuevo webhook y actualiza todas las referencias. Evita editar la URL manualmente. Usa la URL exacta que proporciona Discord.