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 main
 
import (
	"errors"

Parsing and validating CLI flags in Go

cli-parsing validation error-handling
Intermediate 8 steps
go 
package cache
 
import (
	"container/list"

Building a generic LRU cache in Go

lru-cache generics linked-list
Intermediate 8 steps
python 
import time
from collections import defaultdict
from threading import Lock
 

Sliding-window login rate limiting in Flask

rate-limiting sliding-window thread-safety
Intermediate 7 steps
javascript 
const RATE_LIMIT = 100;
const WINDOW_MS = 60 * 1000;
const BLOCK_MS = 5 * 60 * 1000;
 

Building a rate-limiting middleware in Express

rate-limiting middleware closures
Intermediate 9 steps
go 
package model
 
import (
	"encoding/json"

Custom JSON marshaling in Go

json serialization interfaces
Intermediate 5 steps
go 
func (h *TransactionHandler) ExportCSV(c *gin.Context) {
	ctx := c.Request.Context()
	filters := parseTransactionFilters(c)
 

Streaming a CSV export in Gin

streaming csv-export database-cursor
Intermediate 8 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