Laravel + Twilio Integration

3. Bind the REST client and webhook validator

Bind both SDK objects once in AppServiceProvider::register(). The REST client authenticates with an API key and secret; the request validator intentionally uses the account Auth Token.

use Twilio\Rest\Client;
use Twilio\Security\RequestValidator;

public function register(): void
{
    $this->app->singleton(Client::class, fn (): Client => new Client(
        (string) config('services.twilio.api_key'),
        (string) config('services.twilio.api_secret'),
        (string) config('services.twilio.account_sid'),
    ));

    $this->app->singleton(RequestValidator::class, fn (): RequestValidator => new RequestValidator(
        (string) config('services.twilio.auth_token'),
    ));
}

4. Protect send routes and expose one signed callback

Authenticate and throttle user-initiated sends. The status callback remains unauthenticated because Twilio calls it, but it must be HTTPS, signature-validated, and excluded from CSRF validation. A UUID route key lets an early callback find the internal record before the send job saves Twilio's Message SID. The durable record should have a unique UUID, a nullable unique twilio_sid, status, error code, timestamps, and an encrypted or deliberately short-lived body.

use App\Http\Controllers\Messaging\SendSmsController;
use App\Http\Controllers\Messaging\TwilioStatusController;
use Illuminate\Support\Facades\Route;

Route::post('/messages/sms', SendSmsController::class)
    ->middleware(['auth', 'throttle:6,1'])
    ->name('messages.sms.store');

Route::post('/twilio/status/{outboundMessage:uuid}', TwilioStatusController::class)
    ->name('twilio.status');

In a fresh Laravel 12 application, configure validateCsrfTokens(except: ['twilio/status/*']) in bootstrap/app.php. In an upgraded Laravel 10-style structure, add 'twilio/status/*' to VerifyCsrfToken::$except. Keep APP_URL, trusted proxy handling, and the Twilio Console callback on the same public HTTPS URL or signatures will fail.

5. Authorize the contact, enforce consent, and queue the send

Never accept an arbitrary destination from a public controller. Authorize a contact owned by the current user, check recorded consent and opt-out state server-side, then create the durable outbound record before dispatching.

namespace App\Http\Requests\Messaging;

use Illuminate\Foundation\Http\FormRequest;

class SendSmsRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()?->contacts()
            ->whereKey($this->integer('contact_id'))
            ->exists() ?? false;
    }

    public function rules(): array
    {
        return [
            'contact_id' => ['required', 'integer'],
            'message' => ['required', 'string', 'max:320'],
        ];
    }

    public function messages(): array
    {
        return [
            'message.max' => 'Keep SMS messages under 320 characters to control segmentation and cost.',
        ];
    }
}

namespace App\Http\Controllers\Messaging;

use App\Http\Controllers\Controller;
use App\Http\Requests\Messaging\SendSmsRequest;
use App\Jobs\SendSms;
use Illuminate\Http\RedirectResponse;

class SendSmsController extends Controller
{
    public function __invoke(SendSmsRequest $request): RedirectResponse
    {
        $contact = $request->user()->contacts()
            ->findOrFail($request->integer('contact_id'));

        abort_if(
            is_null($contact->sms_consented_at) || $contact->sms_opted_out_at,
            422,
            'This contact cannot receive SMS messages.'
        );

        $outboundMessage = $contact->outboundMessages()->create([
            'body' => $request->validated('message'),
            'status' => 'queued',
        ]);

        SendSms::dispatch($outboundMessage->getKey());

        return back()->with('status', 'Message queued for delivery.');
    }
}

6. Send through a Messaging Service and handle API errors

Recheck consent in the worker because preferences can change after dispatch. This job deliberately allows one attempt: Twilio has no general Message-create idempotency key, so an automatic retry after a response timeout can send a duplicate even if the first API request succeeded.

namespace App\Jobs;

use App\Models\OutboundMessage;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Log;
use Twilio\Exceptions\TwilioException;
use Twilio\Rest\Client;

class SendSms implements ShouldQueue
{
    use Queueable;

    public int $tries = 1;

    public function __construct(public int $outboundMessageId) {}

    public function handle(Client $twilio): void
    {
        $outboundMessage = OutboundMessage::query()
            ->with('contact')
            ->findOrFail($this->outboundMessageId);

        if (is_null($outboundMessage->contact->sms_consented_at) ||
            $outboundMessage->contact->sms_opted_out_at) {
            $outboundMessage->update(['status' => 'skipped']);

            return;
        }

        try {
            $message = $twilio->messages->create(
                $outboundMessage->contact->phone_e164,
                [
                    'messagingServiceSid' => config('services.twilio.messaging_service_sid'),
                    'body' => $outboundMessage->body,
                    'statusCallback' => route('twilio.status', [
                        'outboundMessage' => $outboundMessage->uuid,
                    ]),
                ],
            );

            $outboundMessage->update(['twilio_sid' => $message->sid]);
        } catch (TwilioException $exception) {
            $outboundMessage->update(['status' => 'send_failed']);

            Log::warning('Twilio SMS send failed.', [
                'outbound_message_id' => $outboundMessage->getKey(),
                'twilio_code' => $exception->getCode(),
            ]);

            throw $exception;
        }
    }
}

Do not log the phone number, message body, Auth Token, or API secret. Alert on failed jobs and reconcile ambiguous sends against Twilio message logs before manually retrying. Encrypt or redact stored message bodies according to the product's retention policy.

7. Validate every callback before reading its fields

Twilio signs the exact public URL plus every form parameter and may add parameters without notice. Pass the complete form body to SDK 8.11's RequestValidator; never validate a hand-picked field list or trust IP allowlists.

namespace App\Http\Requests\Messaging;

use App\Models\OutboundMessage;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
use Twilio\Security\RequestValidator;

class TwilioStatusRequest extends FormRequest
{
    public function authorize(RequestValidator $validator): bool
    {
        $outboundMessage = $this->route('outboundMessage');

        if (! $outboundMessage instanceof OutboundMessage) {
            return false;
        }

        return $validator->validate(
            (string) $this->header('X-Twilio-Signature'),
            route('twilio.status', ['outboundMessage' => $outboundMessage->uuid]),
            $this->request->all(),
        );
    }

    public function rules(): array
    {
        return [
            'MessageSid' => ['required', 'string', 'size:34', 'regex:/^(SM|MM)[0-9a-fA-F]{32}$/'],
            'MessageStatus' => [
                'required',
                Rule::in(['accepted', 'queued', 'sending', 'sent', 'delivered', 'undelivered', 'failed', 'read']),
            ],
            'ErrorCode' => ['nullable', 'string', 'max:10'],
        ];
    }
}

8. Record duplicates and prevent out-of-order regressions

Add a unique database constraint such as $table->char('callback_key', 64)->unique() on a non-null callback hash. Do not rely on a composite unique index containing nullable error_code, because several databases allow multiple NULL values. The parent message also needs a boolean status_reconciliation_required column. Lock the parent row, accept the first Message SID, and append every unique callback before updating its summary status. Lower-rank callbacks remain harmless regressions. Because network latency can reorder callbacks and they contain no sequence number, never let arrival order choose between conflicting delivered, undelivered, and failed outcomes. Flag the conflict and fetch the Message resource by SID in an idempotent queued reconciliation job; that canonical API status updates the parent and clears the flag while the callback rows preserve the full audit trail.

namespace App\Http\Controllers\Messaging;

use App\Http\Controllers\Controller;
use App\Http\Requests\Messaging\TwilioStatusRequest;
use App\Jobs\ReconcileTwilioMessageStatus;
use App\Models\OutboundMessage;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;

class TwilioStatusController extends Controller
{
    public function __invoke(
        TwilioStatusRequest $request,
        OutboundMessage $outboundMessage,
    ): Response {
        $data = $request->validated();
        $rank = [
            'accepted' => 0,
            'queued' => 1,
            'sending' => 2,
            'sent' => 3,
            'delivered' => 4,
            'undelivered' => 4,
            'failed' => 4,
            'read' => 5,
        ];
        $terminalStatuses = ['delivered', 'undelivered', 'failed'];

        DB::transaction(function () use (
            $outboundMessage,
            $data,
            $rank,
            $terminalStatuses,
        ): void {
            $message = OutboundMessage::query()
                ->lockForUpdate()
                ->findOrFail($outboundMessage->getKey());

            if ($message->twilio_sid && $message->twilio_sid !== $data['MessageSid']) {
                Log::warning('Twilio callback Message SID mismatch.', [
                    'outbound_message_id' => $message->getKey(),
                ]);

                return;
            }

            if (is_null($message->twilio_sid)) {
                $message->update(['twilio_sid' => $data['MessageSid']]);
            }

            $callback = $message->statusCallbacks()->firstOrCreate([
                'callback_key' => hash('sha256', implode('|', [
                    $data['MessageSid'],
                    $data['MessageStatus'],
                    $data['ErrorCode'] ?? '',
                ])),
            ], [
                'status' => $data['MessageStatus'],
                'error_code' => $data['ErrorCode'] ?? null,
                'received_at' => now(),
            ]);

            if (! $callback->wasRecentlyCreated) {
                return;
            }

            $hasTerminalConflict = $message->status !== $data['MessageStatus']
                && in_array($message->status, $terminalStatuses, true)
                && in_array($data['MessageStatus'], $terminalStatuses, true);

            if ($hasTerminalConflict) {
                $message->update(['status_reconciliation_required' => true]);

                ReconcileTwilioMessageStatus::dispatch($message->getKey())
                    ->afterCommit();

                return;
            }

            $currentRank = $rank[$message->status] ?? -1;
            $newRank = $rank[$data['MessageStatus']];

            if ($newRank > $currentRank || $message->status === $data['MessageStatus']) {
                $message->update([
                    'twilio_sid' => $data['MessageSid'],
                    'status' => $data['MessageStatus'],
                    'error_code' => $data['ErrorCode'] ?? null,
                ]);
            }
        });

        return response()->noContent();
    }
}

The reconciliation job should call $twilio->messages($message->twilio_sid)->fetch() with SDK 8.11.6, then lock the local row, copy the fetched status and errorCode, and clear status_reconciliation_required. Give that job normal retry/backoff behavior: unlike Message creation, fetching by SID is safe to retry. This separates an append-only callback history from the current canonical summary instead of silently discarding a terminal outcome or treating a delayed request as newer evidence.