Step 3: Webhook endpoint (middleware, form request, controller, route)

app/Http/Controllers/EmailWebhookController.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Http\Requests\IncomingEmailRequest;
+use App\Jobs\ProcessIncomingEmail;
+use Illuminate\Http\JsonResponse;
+
+class EmailWebhookController extends Controller
+{
+    /**
+     * Handle an incoming email webhook from MailOps.
+     *
+     * Dispatches the validated payload to a queued job for background
+     * processing and returns immediately with a 200 response.
+     */
+    public function handle(IncomingEmailRequest $request): JsonResponse
+    {
+        ProcessIncomingEmail::dispatch($request->validated());
+
+        return response()->json(['status' => 'queued'], 200);
+    }
+}

app/Http/Middleware/VerifyWebhookSecret.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class VerifyWebhookSecret
+{
+    /**
+     * Verify the incoming webhook request has a valid Bearer token.
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        $secret = config('services.mailops.webhook_secret');
+
+        if (empty($secret)) {
+            return response()->json(['error' => 'Webhook secret not configured'], 500);
+        }
+
+        $token = $request->bearerToken();
+
+        if (! $token || ! hash_equals($secret, $token)) {
+            return response()->json(['error' => 'Unauthorized'], 401);
+        }
+
+        return $next($request);
+    }
+}

app/Http/Requests/IncomingEmailRequest.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class IncomingEmailRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'hash' => ['required', 'string', 'max:64'],
+            'metadata.recipientEmail' => ['required', 'email', 'max:255'],
+            'metadata.recipientName' => ['nullable', 'string', 'max:255'],
+            'metadata.senderEmail' => ['required', 'email', 'max:255'],
+            'metadata.senderName' => ['nullable', 'string', 'max:255'],
+            'metadata.domain' => ['required', 'string', 'max:255'],
+            'metadata.subject' => ['nullable', 'string', 'max:500'],
+            'metadata.received_at' => ['required', 'date'],
+            'metadata.attachments' => ['nullable', 'array'],
+            'metadata.attachments.*.filename' => ['required_with:metadata.attachments', 'string'],
+            'metadata.attachments.*.mimeType' => ['required_with:metadata.attachments', 'string'],
+            'metadata.attachments.*.size' => ['required_with:metadata.attachments', 'integer'],
+            'metadata.attachmentSize' => ['nullable', 'integer', 'min:0'],
+            'bodyText' => ['nullable', 'string'],
+            'bodyHtml' => ['nullable', 'string'],
+        ];
+    }
+
+    /**
+     * Custom error messages.
+     *
+     * @return array<string, string>
+     */
+    public function messages(): array
+    {
+        return [
+            'hash.required' => 'The email hash identifier is required.',
+            'metadata.recipientEmail.required' => 'A recipient email address is required.',
+            'metadata.senderEmail.required' => 'A sender email address is required.',
+            'metadata.domain.required' => 'The recipient domain is required.',
+            'metadata.received_at.required' => 'The email received timestamp is required.',
+        ];
+    }
+}

routes/api.php

@@ -1,3 +1,7 @@
 <?php
 
-// Webhook routes will be added in Step 3
+use App\Http\Controllers\EmailWebhookController;
+use Illuminate\Support\Facades\Route;
+
+Route::post('/webhooks/incoming_email', [EmailWebhookController::class, 'handle'])
+    ->middleware('verify.webhook.secret');