CSRF Token Validation for Modules

This comprehensive guide demonstrates how to properly configure CSRF exclusions in your custom modules for webhook endpoints and API routes that need to bypass CSRF protection while maintaining security best practices.

Prerequisites

Before implementing CSRF exclusions, ensure you have:

• A custom module created for WhatsmarkSaaS
• Understanding of Laravel CSRF protection
• Basic knowledge of webhook and API security

Overview

CSRF (Cross-Site Request Forgery) protection is crucial for web application security, but certain endpoints like webhooks and public APIs need to bypass this protection. This guide shows you how to safely configure CSRF exclusions in your custom modules.

Adding CSRF Exclusions in Your Module

Configure in Module Service Provider

Add CSRF exclusions in your module's service provider register() method:

File: Modules/YourModule/Providers/YourModuleServiceProvider.php

<?php

namespace Modules\YourModule\Providers;

use Illuminate\Support\ServiceProvider;

class YourModuleServiceProvider extends ServiceProvider
{
    public function register()
    {
        // Add CSRF exclusions for your module
        add_filter('csrf_exclusions', function ($exclusions) {
            $moduleExclusions = [
                'your-module/webhook',
                'your-module/api/*',
                'your-module/callback',
            ];
            
            return array_merge($exclusions, $moduleExclusions);
        });
    }
}

Pro Tip

Always use specific route patterns instead of broad wildcards to maintain security.

Common Route Patterns

Here are typical patterns for different types of endpoints:

Basic Example

add_filter('csrf_exclusions', function ($exclusions) {
    $exclusions[] = 'your-module/webhooks/payment';
    $exclusions[] = 'api/your-module/public/*';
    $exclusions[] = 'your-module/oauth/callback';
    return $exclusions;
});

Conditional Exclusions

add_filter('csrf_exclusions', function ($exclusions) {
    // Only add if module feature is enabled
    if (module_enabled('YourModule')) {
        $exclusions[] = 'your-module/webhook';
    }
    
    // Environment-based exclusions
    if (app()->environment('local')) {
        $exclusions[] = 'your-module/test/*';
    }
    
    return $exclusions;
});

Security Best Practices

Important Security Warning

When you exclude routes from CSRF protection, you must implement alternative security measures to prevent attacks.

Required Security Measures

For Webhook Routes:

• Always verify webhook signatures
• Validate request headers and payload structure
• Implement rate limiting

For API Routes:

• Use token-based authentication
• Validate API keys or bearer tokens
• Apply appropriate access controls

General Security:

• Log all requests to excluded routes
• Monitor for suspicious activity
• Use specific route patterns (avoid wildcards)

Testing Your Implementation

Test CSRF Exclusions

Verify that your excluded routes work without CSRF tokens:

• Test webhook endpoints accept POST requests without CSRF tokens
• Verify API endpoints function correctly
• Ensure regular routes still require CSRF protection

Summary

You've learned how to properly configure CSRF exclusions in your custom modules while maintaining security best practices. Remember to always implement alternative security measures for excluded routes.

Next Steps

• Implement webhook signature verification
• Set up API token authentication
• Configure rate limiting for excluded routes
• Test your security implementations

---

Last Updated: October 2025 • Laravel Version: 12.x • WhatsmarkSaaS Module Development