go 45 lines · 6 steps

Verifying GitHub webhooks in Gin

A Gin middleware factory that authenticates GitHub webhook payloads with an HMAC-SHA256 signature before acting on them.

Explained by highlit
Gin Intermediate hmac webhooks middleware authentication constant-time-compare
1package webhooks
2 
3import (
4 "crypto/hmac"
5 "crypto/sha256"
6 "encoding/hex"
7 "io"
8 "net/http"
9 "strings"
10 
11 "github.com/gin-gonic/gin"
12)
13 
14func GitHubHandler(secret string) gin.HandlerFunc {
15 return func(c *gin.Context) {
16 signature := c.GetHeader("X-Hub-Signature-256")
17 if !strings.HasPrefix(signature, "sha256=") {
18 c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing signature"})
19 return
20 }
21 
22 body, err := io.ReadAll(io.LimitReader(c.Request.Body, 1<<20))
23 if err != nil {
24 c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": "unreadable body"})
25 return
26 }
27 
28 mac := hmac.New(sha256.New, []byte(secret))
29 mac.Write(body)
30 expected := mac.Sum(nil)
31 
32 provided, err := hex.DecodeString(strings.TrimPrefix(signature, "sha256="))
33 if err != nil || !hmac.Equal(expected, provided) {
34 c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid signature"})
35 return
36 }
37 
38 switch c.GetHeader("X-GitHub-Event") {
39 case "push":
40 c.JSON(http.StatusAccepted, gin.H{"status": "queued"})
41 default:
42 c.JSON(http.StatusOK, gin.H{"status": "ignored"})
43 }
44 }
45}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Returning a closure over a secret lets you configure a handler at registration time while keeping the secret out of request scope.
  2. 2Always cap request body reads with io.LimitReader so an attacker can't exhaust memory with a huge payload.
  3. 3Compare signatures with hmac.Equal, not ==, to avoid leaking information through timing differences.

Related explainers

javascript 
const ROLE_PERMISSIONS = {
  admin: ['users:read', 'users:write', 'billing:read', 'billing:write'],
  manager: ['users:read', 'billing:read'],
  member: ['users:read'],

Role-based permissions middleware in Express

authorization middleware rbac
Intermediate 9 steps
go 
package handlers
 
import (
	"net/http"

Serving embedded static meta files in Gin

embedding static assets http caching
Intermediate 6 steps
go 
package config
 
import (
	"fmt"

A thread-safe config singleton in Go

singleton concurrency environment-variables
Intermediate 7 steps
javascript 
const express = require('express');
const app = express();
 
app.get('/health', (req, res) => res.json({ status: 'ok' }));

Graceful shutdown in an Express server

graceful-shutdown signal-handling connection-tracking
Advanced 9 steps
php 
<?php
 
namespace App\Http\Middleware;
 

Resolving the current team in Laravel middleware

middleware multi-tenancy cookies
Intermediate 8 steps
go 
package scheduler
 
import (
	"container/heap"

A priority job queue with Go's container/heap

priority-queue heap interfaces
Intermediate 9 steps

Share this explainer

Here's the card — post it anywhere.

Verifying GitHub webhooks in Gin — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code