Sanctum API Keys & Webhooks HMAC
Este módulo detalla los mecanismos de integración para sistemas satélite y aplicaciones de terceros, cubriendo la emisión de API Keys con Laravel Sanctum y la recepción segura de Webhooks mediante firmas criptográficas HMAC-SHA256.
1. Gestión de API Keys con Laravel Sanctum
Los usuarios con el permiso api.tokens.manage pueden generar y revocar llaves de acceso desde su perfil:
- Hashing en Base de Datos: Las llaves se almacenan como hashes SHA-256 en la tabla
personal_access_tokens. - Visibilidad Única: El valor en texto plano (
1|token_secreto...) solo se expone una vez en la sesión flash al ser creado. - Seguridad Transversal: Aplica tanto para la API REST como para el endpoint POST de la API SOAP.
2. Receptor de Webhooks Seguro (VerifyWebhookSignature)
Para consumir eventos externos (pagos, pasarelas, CRMs) sin exponer el sistema a peticiones falsificadas, el endpoint /api/v1/webhooks/receiver exige validación de firma por tiempo constante:
// app/Http/Middleware/Api/VerifyWebhookSignature.php
public function handle(Request $request, Closure $next): Response
{
$signature = $request->header('X-Hub-Signature-256');
if (!$signature) {
return response()->json(['message' => 'Firma no suministrada.'], 403);
}
$secret = env('WEBHOOK_CLIENT_SECRET');
$computedHash = 'sha256=' . hash_hmac('sha256', $request->getContent(), $secret);
// hash_equals previene ataques de temporización (Timing Attacks)
if (!hash_equals($computedHash, $signature)) {
return response()->json(['message' => 'Firma HMAC inválida.'], 403);
}
return $next($request);
}
3. Procesamiento Asíncrono de Webhooks
Para evitar timeouts en los servidores emisores (< 200ms de tolerancia), el webhook no ejecuta la lógica en el controlador:
- Verifica la firma HMAC.
- Persiste el payload íntegro en MongoDB.
- Despacha un Job a Horizon:
HandleWebhookJob::dispatch($payload). - Retorna
200 OKinmediatamente.