How to receive webhooks in Gin Go receiver + reliable processing
A minimal Gin endpoint is easy to add.
Production reliability (verification, retries, idempotency, backpressure) is the hard part — and Hooque makes that part simple.
Prefer the “no framework” version? Read receive webhooks in Go.
TL;DR
- Treat “receive webhooks in Gin (Go)” as an ops problem, not just a route handler.
- Verify the request before parsing/side effects (use a verifySignature(...) stub, then implement provider verification).
- Return 2xx quickly; move work to a worker/queue to avoid timeouts and retries.
- Assume retries and design idempotency (dedupe by event id + unique constraints).
- Log + store raw payloads for replayable debugging.
- If you need one workflow across many providers, centralize ingest + standardize consumption.
Want the standard-library version and shared pitfalls? Read receive webhooks in Go .
Anti-patterns
- Doing business logic inline in the Gin (Go) request handler.
- Parsing/transforming the body before verification (breaks signing inputs).
- Returning 2xx before authenticity is proven.
- Skipping idempotency (retries become double side effects).
Need deeper implementation details? Start with Webhook API.
Table of contents
Why it's hard in production
Frameworks help you build endpoints. They don’t solve retries, replay attacks, or backpressure by default.
Verify authenticity + stop replays
Use a verifySignature(...) stub here, then implement real verification + replay defense for each provider.
Assume retries (duplicates are optional)
Treat every delivery as at-least-once and make side effects idempotent (DB constraints, dedupe keys).
Don’t do work in the request path
Ack fast, process async. Otherwise timeouts, deploys, and spikes turn into missed webhooks.
Debug with real payloads
Save the exact body + headers so you can replay deterministically after a fix.
Add monitoring + alerts early
Track delivered vs rejected, processing latency, queue depth, and error rates.
Iterate locally without losing events
Tunnels help, but durable capture + replay removes the “my laptop was asleep” problem.
Minimal receiver (Gin)
Keep verification as a stub here, then implement provider-specific verification + replay protection in the webhook security guide . For the standard-library version and shared pitfalls, see receive webhooks in Go .
package main
import (
"io"
"net/http"
"github.com/gin-gonic/gin"
)
func verifySignature(headers http.Header, body []byte) error {
// don't compromise on security
// TODO: implement provider-specific signature verification
return nil
}
func processData(body []byte) error {
// TODO: your business logic (DB writes, external API calls, etc.)
return nil
}
func main() {
r := gin.New()
r.POST("/webhooks", func(c *gin.Context) {
body, err := c.GetRawData()
if err != nil {
c.String(http.StatusInternalServerError, "Internal server error")
return
}
if err := verifySignature(c.Request.Header, body); err != nil {
c.String(http.StatusUnauthorized, "Unauthorized")
return
}
// What happens if it fails or times out?
// Most providers retry -> duplicates unless you designed idempotency.
if err := processData(body); err != nil {
// process error (log it, etc.)
}
// IMPORTANT: ack fast to avoid timeouts and duplicate deliveries.
c.String(http.StatusOK, "ok")
})
_ = r.Run(":3000")
}Hooque turns any webhook into a reliable queue.
Non-obvious scenario: you can’t expose a port
In real deployments, the hardest part is often “where does this endpoint run?” (NAT, corporate networks, locked-down environments, short-lived preview deployments). Hooque decouples inbound receiving from processing so your Gin app doesn’t need to be the public receiver.
The easy path: receive with Hooque + consume forever
Receive once (durably), then process from a queue. Your Gin app doesn’t have to be the public receiver.
- Centralize provider-specific verification and reduce “raw body” pitfalls.
- Buffer spikes and deployments so you don’t drop deliveries.
- Use explicit Ack / Nack / Reject to control retries.
- Replay from the UI after a fix (no guessing what payload was sent).
Want the generic patterns? Read Webhook API and migrate to queue-based processing.
Hooque REST polling loop (runs forever)
Poll the queue forever and handle each event outside the provider’s request path.
// Go 1.22+ (net/http)
// Runs forever: poll /next, ack/nack/reject explicitly.
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"os"
"strings"
"time"
)
type Msg struct {
Payload any
Meta map[string]any
}
func main() {
nextURL := getenv("HOOQUE_QUEUE_NEXT_URL", "https://app.hooque.io/queues/<consumerId>/next")
token := getenv("HOOQUE_TOKEN", "hq_tok_replace_me")
client := &http.Client{Timeout: 30 * time.Second}
ctx := context.Background()
log.Println("Starting Hooque REST consumer...")
for {
msg, err := getNextMessage(ctx, client, nextURL, token)
if err != nil {
log.Printf("Worker connection error: %v", err)
time.Sleep(2 * time.Second)
continue
}
if msg == nil {
time.Sleep(1 * time.Second)
continue
}
if err := processData(msg.Payload, msg.Meta); err == nil {
ack(ctx, client, msg, token)
} else {
nack(ctx, client, msg, token, err)
}
}
}
func processData(payload any, meta map[string]any) error {
// Example real-life task: run a script on webhook events.
msgID := "unknown"
if id, ok := meta["messageId"]; ok {
msgID = fmt.Sprintf("%v", id)
}
log.Printf("Processing event: %s", msgID)
// Example: exec.Command("...").Run()
return nil
}
func getNextMessage(ctx context.Context, client *http.Client, nextURL, token string) (*Msg, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, nextURL, nil)
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
req.Header.Set("Authorization", "Bearer "+token)
resp, err := client.Do(req)
if err != nil {
return nil, fmt.Errorf("next() fetch error: %w", err)
}
defer resp.Body.Close()
if resp.StatusCode == http.StatusNoContent {
return nil, nil
}
bodyBytes, err := io.ReadAll(resp.Body)
if err != nil {
return nil, fmt.Errorf("failed to read response body: %w", err)
}
if resp.StatusCode >= 400 {
return nil, fmt.Errorf("next() failed: status=%d body=%s", resp.StatusCode, string(bodyBytes))
}
metaRaw := resp.Header.Get("X-Hooque-Meta")
if metaRaw == "" {
metaRaw = "{}"
}
meta := make(map[string]any)
if err := json.Unmarshal([]byte(metaRaw), &meta); err != nil {
log.Printf("Failed to decode meta header: %v", err)
}
contentType := resp.Header.Get("Content-Type")
// Keep it simple: treat as string; parse JSON if you know content-type is JSON.
var payload any = string(bodyBytes)
if strings.Contains(strings.ToLower(contentType), "json") {
if err := json.Unmarshal(bodyBytes, &payload); err != nil {
log.Printf("Failed to decode JSON payload: %v", err)
}
}
return &Msg{Payload: payload, Meta: meta}, nil
}
func ack(ctx context.Context, client *http.Client, msg *Msg, token string) {
if ackURL, ok := msg.Meta["ackUrl"].(string); ok {
postAck(ctx, client, ackURL, token, "")
}
}
func nack(ctx context.Context, client *http.Client, msg *Msg, token string, err error) {
nackURL, ok := msg.Meta["nackUrl"].(string)
if !ok {
nackURL, _ = msg.Meta["rejectUrl"].(string)
}
if nackURL != "" {
postAck(ctx, client, nackURL, token, err.Error())
}
}
func postAck(ctx context.Context, client *http.Client, urlStr, token, reason string) {
var body io.Reader
if reason != "" {
b, err := json.Marshal(map[string]string{"reason": reason})
if err == nil {
body = bytes.NewReader(b)
}
}
req, err := http.NewRequestWithContext(ctx, http.MethodPost, urlStr, body)
if err != nil {
log.Printf("Failed to create ack request: %v", err)
return
}
req.Header.Set("Authorization", "Bearer "+token)
if reason != "" {
req.Header.Set("Content-Type", "application/json")
}
// asynchronously ack the message
resp, err := client.Do(req)
if err != nil {
log.Printf("Ack request failed: %v", err)
return
}
resp.Body.Close()
}
func getenv(key, fallback string) string {
if v := os.Getenv(key); v != "" {
return v
}
return fallback
}Hooque SSE stream consumer (runs forever)
Stream events in real time and reconnect forever on disconnects.
// Go 1.22+ — SSE consumer (net/http)
// Runs forever: connect to /stream, handle "message" events, ack/nack/reject explicitly.
package main
import (
"bufio"
"bytes"
"context"
"encoding/base64"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"os"
"strings"
"time"
)
type SseMsg struct {
ContentType string `json:"contentType"`
Encoding string `json:"encoding"`
Payload string `json:"payload"`
Meta map[string]any `json:"meta"`
}
type Msg struct {
Payload string
Meta map[string]any
}
func main() {
streamURL := getenv("HOOQUE_QUEUE_STREAM_URL", "https://app.hooque.io/queues/<consumerId>/stream")
token := getenv("HOOQUE_TOKEN", "hq_tok_replace_me")
client := &http.Client{Timeout: 0} // Stream connection, no timeout
ctx := context.Background()
log.Println("Starting Hooque SSE consumer...")
msgChan := make(chan Msg)
go getMessageStream(ctx, client, streamURL, token, msgChan)
for msg := range msgChan {
if err := processData(msg.Payload, msg.Meta); err == nil {
ack(ctx, client, &msg, token)
} else {
nack(ctx, client, &msg, token, err)
}
}
}
func processData(payload any, meta map[string]any) error {
log.Printf("Processing event: %v", meta["messageId"])
return nil
}
func getMessageStream(ctx context.Context, client *http.Client, streamURL, token string, msgChan chan<- Msg) {
for {
if err := connectAndProcess(ctx, client, streamURL, token, msgChan); err != nil {
log.Printf("Stream error: %v", err)
time.Sleep(2 * time.Second)
}
}
}
func connectAndProcess(ctx context.Context, client *http.Client, streamURL, token string, msgChan chan<- Msg) error {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, streamURL, nil)
if err != nil {
return fmt.Errorf("failed to create stream request: %w", err)
}
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Accept", "text/event-stream")
// connect stream, retry automatically on network errors
resp, err := client.Do(req)
if err != nil || resp.StatusCode >= 400 {
if resp != nil && resp.Body != nil {
resp.Body.Close()
}
return fmt.Errorf("request failed: %v", err)
}
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
// Increase buffer size to handle larger payloads
scanner.Buffer(make([]byte, 0, 64*1024), 2*1024*1024)
event := ""
var dataLines []string
// defensive chunk reading to keep loop alive when stream drops
for scanner.Scan() {
line := strings.TrimRight(scanner.Text(), "\r")
if strings.HasPrefix(line, ":") {
continue
}
// Empty line marks the end of an event
if line == "" {
if event == "message" && len(dataLines) > 0 {
var sseMsg SseMsg
// safe parsing without crashing the stream loop
if err := json.Unmarshal([]byte(strings.Join(dataLines, "\n")), &sseMsg); err == nil {
payload := decodePayload(sseMsg)
msgChan <- Msg{Payload: payload, Meta: sseMsg.Meta}
}
}
// Reset for next event
event = ""
dataLines = nil
continue
}
if strings.HasPrefix(line, "event:") {
event = strings.TrimSpace(line[6:])
continue
}
if strings.HasPrefix(line, "data:") {
dataLines = append(dataLines, strings.TrimSpace(line[5:]))
continue
}
}
if err := scanner.Err(); err != nil {
return fmt.Errorf("scanner error: %w", err)
}
return nil
}
func decodePayload(msg SseMsg) string {
raw := msg.Payload
if msg.Encoding == "base64" {
if b, err := base64.StdEncoding.DecodeString(raw); err == nil {
raw = string(b)
}
}
// For JSON the caller can parse
return raw
}
func ack(ctx context.Context, client *http.Client, msg *Msg, token string) {
if ackURL, ok := msg.Meta["ackUrl"].(string); ok {
postAck(ctx, client, ackURL, token, nil)
}
}
func nack(ctx context.Context, client *http.Client, msg *Msg, token string, err error) {
nackURL, ok := msg.Meta["nackUrl"].(string)
if !ok {
nackURL, _ = msg.Meta["rejectUrl"].(string)
}
if nackURL != "" {
b, _ := json.Marshal(map[string]string{"reason": err.Error()})
postAck(ctx, client, nackURL, token, b)
}
}
func postAck(ctx context.Context, client *http.Client, urlStr, token string, jsonBody []byte) {
var body io.Reader
if len(jsonBody) > 0 {
body = bytes.NewReader(jsonBody)
}
req, err := http.NewRequestWithContext(ctx, http.MethodPost, urlStr, body)
if err != nil {
log.Printf("Failed to create post request: %v", err)
return
}
req.Header.Set("Authorization", "Bearer "+token)
if len(jsonBody) > 0 {
req.Header.Set("Content-Type", "application/json")
}
resp, err := client.Do(req)
if err != nil {
log.Printf("Post request failed: %v", err)
return
}
resp.Body.Close()
}
func getenv(key, fallback string) string {
if v := os.Getenv(key); v != "" {
return v
}
return fallback
}FAQ
Answers tailored to Gin, plus shared webhook production guidance.
How do I get the raw request body in Gin?
General: Signature verification typically requires the raw body bytes (before JSON parsing). Ensure your middleware stack does not transform the body before verification.
How Hooque helps: With Hooque, provider delivery goes to a managed ingest endpoint. Your worker consumes from a queue using REST or SSE, so the “raw body vs parsed body” pitfall is mostly confined to ingest configuration.
What status code should I return for webhooks in Gin (Go)?
General: Usually return a fast 2xx after validating authenticity and basic schema. Timeouts and 5xx commonly trigger retries.
How Hooque helps: Hooque acknowledges ingest immediately and persists the payload. Your worker acks/nacks/rejects explicitly after processing.
Do I need signature verification in Gin (Go)?
General: Yes, unless the sender is fully trusted and on a private network. A public endpoint without verification is easy to forge and easy to replay.
How Hooque helps: Hooque can verify at ingest for supported providers or using generic strategies. Either way, your worker receives a normalized meta object and can stay focused on processing.
Why do I see duplicate webhook events in Gin (Go)?
General: Retries are normal: timeouts, transient network failures, and 5xx responses all produce duplicates. Design idempotency around event ids and side-effect boundaries.
How Hooque helps: Hooque makes delivery outcomes explicit (ack/nack/reject) and provides replay/inspection so you can fix issues without guessing what was received.
How do I test webhooks locally in Gin (Go)?
General: You can use a tunnel, but local dev still breaks on sleep, VPNs, clock skew, and signature-byte mismatches.
How Hooque helps: With Hooque you can avoid inbound locally: receive events into a durable queue and pull/stream to your laptop, then replay from the UI after changes.
Should I use REST polling or SSE streaming for webhook processing?
General: Use REST polling for simple batch workers and environments without long-lived connections. Use SSE for low-latency “process as it arrives” flows.
How Hooque helps: Hooque supports both: `GET /next` for polling and `GET /stream` for streaming. Both include meta with ready-to-call ack/nack/reject URLs.
Start processing webhooks reliably
Use Gin for your app, and keep webhook processing as a simple run-forever consumer loop with explicit ack/nack/reject control.
No credit card required