Blog Protege tus Webhooks en Laravel: seguridad con tokens y logs

Los webhooks son una forma poderosa de recibir notificaciones automáticas de servicios externos como MercadoPago, Stripe o WhatsApp. Pero si no los proteges adecuadamente, pueden convertirse en un punto vulnerable de tu aplicación Laravel.

En este artículo, aprenderás cómo proteger tus webhooks usando un token secreto y registrar sus eventos en logs.

1. ¿Por qué proteger un webhook?

Un webhook es simplemente una URL pública que puede ser atacada si no se valida correctamente. Un atacante podría enviar datos falsos a tu endpoint y simular transacciones, cambios de estado u otras acciones críticas.

2. Ruta del webhook

// routes/api.php
Route::post('/webhook/mercadopago', [WebhookController::class, 'handle']);
  

3. Agrega un token secreto a tu .env

# .env
WEBHOOK_SECRET=mi-token-ultra-secreto

4. Protege tu webhook en el controlador

Antes de procesar cualquier evento, verifica si el token es válido:

// app/Http/Controllers/WebhookController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        $secret = config('services.webhook.secret');
        $incomingToken = $request->header('X-Hook-Token');

        if ($incomingToken !== $secret) {
            Log::warning('Webhook rechazado: token inválido', [
                'ip' => $request->ip(),
                'headers' => $request->headers->all(),
            ]);

            return response()->json(['error' => 'Unauthorized'], 401);
        }

        Log::info('Webhook recibido correctamente', $request->all());

        // Procesar evento
        return response()->json(['status' => 'ok']);
    }
}
  

5. Configura el servicio en config/services.php

'webhook' => [
    'secret' => env('WEBHOOK_SECRET'),
],

6. Recomendaciones extra

• Si la plataforma lo permite, firma el cuerpo del webhook y valida el hash.
• Limita la IP o rango de IPs desde donde aceptas llamadas.
• Usa HTTPS siempre (Laravel ya lo recomienda por defecto).
• Evita exponer datos sensibles en respuestas o logs.
• Guarda los logs por tipo y crea alertas ante errores.

7. Ejemplo de log personalizado

Si quieres usar un canal exclusivo para webhooks, puedes crear uno en config/logging.php:

'channels' => [
    'webhook' => [
        'driver' => 'single',
        'path' => storage_path('logs/webhook.log'),
        'level' => 'info',
    ],
],

Y luego en tu controlador:

\Log::channel('webhook')->info('Evento recibido', $request->all());

Conclusión

Proteger los webhooks en Laravel es una tarea sencilla pero vital. Usar tokens, validaciones de headers y registros en logs te puede ahorrar muchos dolores de cabeza y reforzar la seguridad de tu sistema.

¿Ya estás protegiendo tus webhooks? ¿Te gustaría aprender a verificar firmas con HMAC o a simular webhooks en local? ¡Déjamelo saber y lo armamos en otro post!