php 41 lines · 5 steps

Verifying GitHub webhook signatures in Laravel

A Laravel middleware that authenticates incoming GitHub webhooks by recomputing and comparing their HMAC signature.

Explained by highlit

Laravel Intermediate middleware hmac webhooks authentication timing-safe-comparison

1<?php
2 
3namespace App\Http\Middleware;
4 
5use Closure;
6use Illuminate\Http\Request;
7use Illuminate\Support\Facades\Log;
8use Symfony\Component\HttpFoundation\Response;
9 
10class VerifyGitHubSignature
11{
12    public function handle(Request $request, Closure $next): Response
13    {
14        $signature = $request->header('X-Hub-Signature-256');
15 
16        if (! $signature || ! str_starts_with($signature, 'sha256=')) {
17            Log::warning('GitHub webhook rejected: missing signature', [
18                'delivery' => $request->header('X-GitHub-Delivery'),
19            ]);
20 
21            abort(Response::HTTP_UNAUTHORIZED, 'Missing signature.');
22        }
23 
24        $expected = 'sha256=' . hash_hmac(
25            'sha256',
26            $request->getContent(),
27            (string) config('services.github.webhook_secret'),
28        );
29 
30        if (! hash_equals($expected, $signature)) {
31            Log::warning('GitHub webhook rejected: signature mismatch', [
32                'delivery' => $request->header('X-GitHub-Delivery'),
33                'event' => $request->header('X-GitHub-Event'),
34            ]);
35 
36            abort(Response::HTTP_UNAUTHORIZED, 'Invalid signature.');
37        }
38 
39        return $next($request);
40    }
41}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Webhook authenticity is proven by recomputing an HMAC over the raw body with a shared secret and comparing it to the sender's header.
2Always use a constant-time comparison like hash_equals for secrets to avoid leaking information through timing.
3Middleware is the natural place to reject unauthenticated requests before they ever reach your business logic.

Related explainers

java

@Configuration
@EnableWebSecurity
public class OAuth2SecurityConfig {

How OIDC login works in Spring Security

oauth2 openid-connect authorization

Intermediate 8 steps

php

<?php
 
namespace App\Models;

How Eloquent scopes model order status in Laravel

query scopes state machine eloquent

Intermediate 7 steps

typescript

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { ConfigService } from '@nestjs/config';

How a JWT strategy authenticates in NestJS

authentication jwt passport

Intermediate 7 steps

php

<?php
 
namespace App\Http\Controllers;

Streaming a filtered CSV export in Laravel

streaming csv-export query-builder

Intermediate 9 steps

typescript

import { Injectable } from '@angular/core';
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http';
import { BehaviorSubject, Observable, throwError } from 'rxjs';
import { catchError, filter, take, switchMap } from 'rxjs/operators';