feat: Add webhook signature verification using Meta App Secret (#62)

- Add AppSecret field to WhatsAppAccount model for storing Meta App Secret
- Update accounts API to handle app_secret in create/update operations
- Add HasAppSecret indicator in account response
- Include AppSecret in WhatsApp account cache for efficient lookups
- Verify X-Hub-Signature-256 header using HMAC-SHA256 with App Secret
- Signature verification happens inline during message processing (no double loop)
- Add app_secret input field and status badge in frontend AccountsView
- Add comprehensive unit tests for signature verification function

Author: shridarpatil

frontend/src/views/settings/AccountsView.vue

@@ -73,6 +73,7 @@ interface WhatsAppAccount {
   auto_read_receipt: boolean
   status: string
   has_access_token: boolean
+  has_app_secret: boolean
   phone_number?: string
   display_name?: string
   created_at: string
@@ -106,6 +107,7 @@ const formData = ref({
   phone_id: '',
   business_id: '',
   access_token: '',
+  app_secret: '',
   webhook_verify_token: '',
   api_version: 'v21.0',
   is_default_incoming: false,
@@ -144,6 +146,7 @@ function openCreateDialog() {
     phone_id: '',
     business_id: '',
     access_token: '',
+    app_secret: '',
     webhook_verify_token: '',
     api_version: 'v21.0',
     is_default_incoming: false,
@@ -161,6 +164,7 @@ function openEditDialog(account: WhatsAppAccount) {
     phone_id: account.phone_id,
     business_id: account.business_id,
     access_token: '', // Don't show existing token
+    app_secret: '', // Don't show existing secret
     webhook_verify_token: account.webhook_verify_token,
     api_version: account.api_version,
     is_default_incoming: account.is_default_incoming,
@@ -184,10 +188,13 @@ async function saveAccount() {
   isSubmitting.value = true
   try {
     const payload = { ...formData.value }
-    // Don't send empty access token when editing
+    // Don't send empty access token or app secret when editing
     if (editingAccount.value && !payload.access_token) {
       delete (payload as any).access_token
     }
+    if (editingAccount.value && !payload.app_secret) {
+      delete (payload as any).app_secret
+    }
 
     if (editingAccount.value) {
       await api.put(`/accounts/${editingAccount.value.id}`, payload)
@@ -418,6 +425,15 @@ const webhookUrl = window.location.origin + basePath + '/api/webhook'
                         {{ account.has_access_token ? 'Configured' : 'Missing' }}
                       </Badge>
                     </div>
+                    <div class="flex items-center gap-2">
+                      <span class="text-white/50 light:text-gray-500">App Secret:</span>
+                      <Badge
+                        variant="outline"
+                        :class="account.has_app_secret ? 'border-green-600 text-green-600' : 'border-yellow-600 text-yellow-600'"
+                      >
+                        {{ account.has_app_secret ? 'Configured' : 'Not Set' }}
+                      </Badge>
+                    </div>
                   </div>
 
                   <!-- Defaults -->
@@ -598,6 +614,22 @@ const webhookUrl = window.location.origin + basePath + '/api/webhook'
             </p>
           </div>
 
+          <div class="space-y-2">
+            <Label for="app_secret">
+              App Secret
+              <span v-if="editingAccount" class="text-muted-foreground">(leave blank to keep existing)</span>
+            </Label>
+            <Input
+              id="app_secret"
+              v-model="formData.app_secret"
+              type="password"
+              placeholder="Meta App Secret for webhook verification"
+            />
+            <p class="text-xs text-muted-foreground">
+              Found in Meta Developer Console &gt; App Settings &gt; Basic &gt; App Secret. Used to verify webhook signatures.
+            </p>
+          </div>
+
           <Separator />
 
           <div class="space-y-2">

internal/handlers/accounts.go

@@ -21,6 +21,7 @@ type AccountRequest struct {
 	PhoneID            string `json:"phone_id" validate:"required"`
 	BusinessID         string `json:"business_id" validate:"required"`
 	AccessToken        string `json:"access_token" validate:"required"`
+	AppSecret          string `json:"app_secret"` // Meta App Secret for webhook signature verification
 	WebhookVerifyToken string `json:"webhook_verify_token"`
 	APIVersion         string `json:"api_version"`
 	IsDefaultIncoming  bool   `json:"is_default_incoming"`
@@ -42,6 +43,7 @@ type AccountResponse struct {
 	AutoReadReceipt    bool      `json:"auto_read_receipt"`
 	Status             string    `json:"status"`
 	HasAccessToken     bool      `json:"has_access_token"`
+	HasAppSecret       bool      `json:"has_app_secret"`
 	PhoneNumber        string    `json:"phone_number,omitempty"`
 	DisplayName        string    `json:"display_name,omitempty"`
 	CreatedAt          string    `json:"created_at"`
@@ -108,6 +110,7 @@ func (a *App) CreateAccount(r *fastglue.Request) error {
 		PhoneID:            req.PhoneID,
 		BusinessID:         req.BusinessID,
 		AccessToken:        req.AccessToken, // TODO: encrypt before storing
+		AppSecret:          req.AppSecret,   // Meta App Secret for webhook signature verification
 		WebhookVerifyToken: webhookVerifyToken,
 		APIVersion:         apiVersion,
 		IsDefaultIncoming:  req.IsDefaultIncoming,
@@ -199,6 +202,9 @@ func (a *App) UpdateAccount(r *fastglue.Request) error {
 	if req.AccessToken != "" {
 		account.AccessToken = req.AccessToken // TODO: encrypt
 	}
+	if req.AppSecret != "" {
+		account.AppSecret = req.AppSecret
+	}
 	if req.WebhookVerifyToken != "" {
 		account.WebhookVerifyToken = req.WebhookVerifyToken
 	}
@@ -336,6 +342,7 @@ func accountToResponse(acc models.WhatsAppAccount) AccountResponse {
 		AutoReadReceipt:    acc.AutoReadReceipt,
 		Status:             acc.Status,
 		HasAccessToken:     acc.AccessToken != "",
+		HasAppSecret:       acc.AppSecret != "",
 		CreatedAt:          acc.CreatedAt.Format("2006-01-02T15:04:05Z"),
 		UpdatedAt:          acc.UpdatedAt.Format("2006-01-02T15:04:05Z"),
 	}

internal/handlers/cache.go

@@ -204,10 +204,11 @@ func (a *App) deleteKeysByPattern(ctx context.Context, pattern string) {
 	}
 }
 
-// whatsAppAccountCache is used for caching since AccessToken has json:"-" tag
+// whatsAppAccountCache is used for caching since AccessToken and AppSecret have json:"-" tag
 type whatsAppAccountCache struct {
 	models.WhatsAppAccount
 	AccessToken string `json:"access_token"`
+	AppSecret   string `json:"app_secret"`
 }
 
 // getWhatsAppAccountCached retrieves WhatsApp account by phone_id from cache or database
@@ -221,6 +222,7 @@ func (a *App) getWhatsAppAccountCached(phoneID string) (*models.WhatsAppAccount,
 		var cacheData whatsAppAccountCache
 		if err := json.Unmarshal([]byte(cached), &cacheData); err == nil {
 			cacheData.WhatsAppAccount.AccessToken = cacheData.AccessToken
+			cacheData.WhatsAppAccount.AppSecret = cacheData.AppSecret
 			return &cacheData.WhatsAppAccount, nil
 		}
 	}
@@ -231,10 +233,11 @@ func (a *App) getWhatsAppAccountCached(phoneID string) (*models.WhatsAppAccount,
 		return nil, err
 	}
 
-	// Cache the result (include AccessToken explicitly)
+	// Cache the result (include AccessToken and AppSecret explicitly since they have json:"-")
 	cacheData := whatsAppAccountCache{
 		WhatsAppAccount: account,
 		AccessToken:     account.AccessToken,
+		AppSecret:       account.AppSecret,
 	}
 	if data, err := json.Marshal(cacheData); err == nil {
 		a.Redis.Set(ctx, cacheKey, data, whatsappAccountCacheTTL)

internal/handlers/webhook.go

@@ -1,6 +1,10 @@
 package handlers
 
 import (
+	"bytes"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"strings"
 
@@ -183,12 +187,18 @@ type WebhookPayload struct {
 
 // WebhookHandler processes incoming webhook events from Meta
 func (a *App) WebhookHandler(r *fastglue.Request) error {
+	body := r.RequestCtx.PostBody()
+	signature := r.RequestCtx.Request.Header.Peek("X-Hub-Signature-256")
+
 	var payload WebhookPayload
-	if err := json.Unmarshal(r.RequestCtx.PostBody(), &payload); err != nil {
+	if err := json.Unmarshal(body, &payload); err != nil {
 		a.Log.Error("Failed to parse webhook payload", "error", err)
 		return r.SendErrorEnvelope(fasthttp.StatusBadRequest, "Invalid payload", nil, "")
 	}
 
+	// Track if signature has been verified (only need to verify once per request)
+	signatureVerified := false
+
 	// Process each entry
 	for _, entry := range payload.Entry {
 		for _, change := range entry.Changes {
@@ -210,6 +220,19 @@ func (a *App) WebhookHandler(r *fastglue.Request) error {
 
 			phoneNumberID := change.Value.Metadata.PhoneNumberID
 
+			// Verify webhook signature on first message processing (uses cached account)
+			if !signatureVerified && len(signature) > 0 && phoneNumberID != "" {
+				account, err := a.getWhatsAppAccountCached(phoneNumberID)
+				if err == nil && account.AppSecret != "" {
+					if !verifyWebhookSignature(body, signature, []byte(account.AppSecret)) {
+						a.Log.Warn("Invalid webhook signature", "phone_id", phoneNumberID)
+						return r.SendErrorEnvelope(fasthttp.StatusForbidden, "Invalid signature", nil, "")
+					}
+					a.Log.Debug("Webhook signature verified successfully")
+				}
+				signatureVerified = true
+			}
+
 			// Process messages
 			for _, msg := range change.Value.Messages {
 				a.Log.Info("Received message",
@@ -421,3 +444,24 @@ func (a *App) processTemplateStatusUpdate(wabaID, event, templateName, templateL
 		}
 	}
 }
+
+// verifyWebhookSignature verifies the X-Hub-Signature-256 header from Meta.
+// The signature is HMAC-SHA256 of the request body using the App Secret.
+func verifyWebhookSignature(body, signature, appSecret []byte) bool {
+	// Signature format: "sha256=<hex_signature>"
+	prefix := []byte("sha256=")
+	if !bytes.HasPrefix(signature, prefix) {
+		return false
+	}
+
+	expectedSig := bytes.TrimPrefix(signature, prefix)
+
+	// Compute HMAC-SHA256
+	mac := hmac.New(sha256.New, appSecret)
+	mac.Write(body)
+	computedSig := make([]byte, hex.EncodedLen(mac.Size()))
+	hex.Encode(computedSig, mac.Sum(nil))
+
+	// Constant-time comparison to prevent timing attacks
+	return hmac.Equal(expectedSig, computedSig)
+}

internal/handlers/webhook_test.go

@@ -0,0 +1,136 @@
+package handlers
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestVerifyWebhookSignature(t *testing.T) {
+	t.Parallel()
+
+	// Test data
+	appSecret := []byte("test_app_secret_12345")
+	body := []byte(`{"object":"whatsapp_business_account","entry":[{"id":"123","changes":[]}]}`)
+
+	// Compute valid signature
+	mac := hmac.New(sha256.New, appSecret)
+	mac.Write(body)
+	validSig := "sha256=" + hex.EncodeToString(mac.Sum(nil))
+
+	tests := []struct {
+		name      string
+		body      []byte
+		signature []byte
+		appSecret []byte
+		want      bool
+	}{
+		{
+			name:      "valid signature",
+			body:      body,
+			signature: []byte(validSig),
+			appSecret: appSecret,
+			want:      true,
+		},
+		{
+			name:      "invalid signature - wrong hash",
+			body:      body,
+			signature: []byte("sha256=0000000000000000000000000000000000000000000000000000000000000000"),
+			appSecret: appSecret,
+			want:      false,
+		},
+		{
+			name:      "invalid signature - wrong secret",
+			body:      body,
+			signature: []byte(validSig),
+			appSecret: []byte("wrong_secret"),
+			want:      false,
+		},
+		{
+			name:      "invalid signature - modified body",
+			body:      []byte(`{"object":"modified"}`),
+			signature: []byte(validSig),
+			appSecret: appSecret,
+			want:      false,
+		},
+		{
+			name:      "invalid signature - missing sha256 prefix",
+			body:      body,
+			signature: []byte(hex.EncodeToString(mac.Sum(nil))),
+			appSecret: appSecret,
+			want:      false,
+		},
+		{
+			name:      "invalid signature - wrong prefix",
+			body:      body,
+			signature: []byte("sha1=" + hex.EncodeToString(mac.Sum(nil))),
+			appSecret: appSecret,
+			want:      false,
+		},
+		{
+			name:      "empty signature",
+			body:      body,
+			signature: []byte{},
+			appSecret: appSecret,
+			want:      false,
+		},
+		{
+			name:      "empty body with valid signature for empty body",
+			body:      []byte{},
+			signature: func() []byte {
+				m := hmac.New(sha256.New, appSecret)
+				m.Write([]byte{})
+				return []byte("sha256=" + hex.EncodeToString(m.Sum(nil)))
+			}(),
+			appSecret: appSecret,
+			want:      true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := verifyWebhookSignature(tt.body, tt.signature, tt.appSecret)
+			assert.Equal(t, tt.want, got, "verifyWebhookSignature() = %v, want %v", got, tt.want)
+		})
+	}
+}
+
+func TestVerifyWebhookSignature_RealWorldExample(t *testing.T) {
+	t.Parallel()
+
+	// Simulate a real Meta webhook payload
+	payload := `{"object":"whatsapp_business_account","entry":[{"id":"123456789","changes":[{"value":{"messaging_product":"whatsapp","metadata":{"display_phone_number":"15551234567","phone_number_id":"987654321"},"messages":[{"from":"15559876543","id":"wamid.abc123","timestamp":"1234567890","type":"text","text":{"body":"Hello"}}]},"field":"messages"}]}]}`
+	appSecret := "my_app_secret_from_meta_dashboard"
+
+	// Compute signature like Meta would
+	mac := hmac.New(sha256.New, []byte(appSecret))
+	mac.Write([]byte(payload))
+	signature := "sha256=" + hex.EncodeToString(mac.Sum(nil))
+
+	// Verify
+	result := verifyWebhookSignature([]byte(payload), []byte(signature), []byte(appSecret))
+	assert.True(t, result, "Should verify real-world webhook payload")
+}
+
+func TestVerifyWebhookSignature_TimingAttackResistance(t *testing.T) {
+	t.Parallel()
+
+	// This test ensures we use constant-time comparison
+	// by verifying the function behaves correctly with similar signatures
+	appSecret := []byte("test_secret")
+	body := []byte("test body")
+
+	mac := hmac.New(sha256.New, appSecret)
+	mac.Write(body)
+	validSig := "sha256=" + hex.EncodeToString(mac.Sum(nil))
+
+	// Create a signature that differs only in the last character
+	almostValidSig := validSig[:len(validSig)-1] + "0"
+
+	assert.True(t, verifyWebhookSignature(body, []byte(validSig), appSecret))
+	assert.False(t, verifyWebhookSignature(body, []byte(almostValidSig), appSecret))
+}

internal/models/models.go

@@ -271,6 +271,7 @@ type WhatsAppAccount struct {
 	PhoneID            string    `gorm:"size:100;not null" json:"phone_id"`
 	BusinessID         string    `gorm:"size:100;not null" json:"business_id"`
 	AccessToken        string    `gorm:"type:text;not null" json:"-"` // encrypted
+	AppSecret          string    `gorm:"size:255" json:"-"`           // Meta App Secret for webhook signature verification
 	WebhookVerifyToken string    `gorm:"size:255" json:"webhook_verify_token"`
 	APIVersion         string    `gorm:"size:20;default:'v21.0'" json:"api_version"`
 	IsDefaultIncoming  bool      `gorm:"default:false" json:"is_default_incoming"`