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

go 
package streaming
 
import (
	"bufio"

Streaming NDJSON logs over HTTP in Go

http-streaming channels select
Advanced 10 steps
python 
import time
import uuid
 
from django.utils.deprecation import MiddlewareMixin

Attaching per-request context in Django

middleware request lifecycle multi-tenancy
Intermediate 7 steps
go 
package api
 
import (
	"crypto/sha256"

ETag conditional requests in Gin

http-caching etag conditional-requests
Intermediate 6 steps
go 
func (w *Watcher) resetDebounce(d time.Duration) {
	if !w.timer.Stop() {
		select {
		case <-w.timer.C:

Debouncing a stream of events in Go

debounce timers channels
Advanced 7 steps
go 
package logging
 
import (
	"context"

Deduplicating log attributes in Go's slog

decorator-pattern structured-logging immutability
Intermediate 8 steps
go 
package middleware
 
import (
	"net/http"

Per-plan export limits in Gin middleware

middleware rate-limiting authorization
Intermediate 7 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