second commit

2026-06-04 15:44:48 +08:00
parent 4db6efb3a7
commit 8ac150bc7b
1275 changed files with 286124 additions and 0 deletions
@@ -0,0 +1,83 @@
+// Package webhook provides Gin-compatible HTTP handler adapters for external
+// channel webhook endpoints. Each adapter wraps the corresponding channel
+// sub-package's WebhookHandler and exposes methods that can be bound directly
+// to Gin router groups.
+package webhook
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"github.com/gochat/gochat/internal/channel/whatsapp"
+)
+
+// WhatsAppWebhookHandler is a Gin adapter that wraps the WhatsApp
+// sub-package's WebhookHandler. It translates Gin context calls into the
+// underlying handler methods so that WhatsApp webhook routes can be registered
+// on a Gin engine with minimal glue code.
+//
+// Chatwoot-style routes:
+//
+//   GET  /webhooks/whatsapp/:phone_number        → HandleWhatsAppVerification
+//   POST /webhooks/whatsapp/:phone_number        → HandleWhatsAppWebhook
+//
+// WhatsApp Cloud API webhook verification (GET):
+//
+//   The Meta platform sends a GET request with query parameters:
+//     - hub.mode          = "subscribe"
+//     - hub.verify_token  = the token configured in the Meta dashboard
+//     - hub.challenge     = a string the endpoint must echo back verbatim
+//
+//   The handler validates hub.verify_token against the stored token and
+//   returns hub.challenge as the response body with HTTP 200, or returns
+//   HTTP 403 on mismatch.
+//
+// WhatsApp Cloud API webhook events (POST):
+//
+//   Meta delivers event payloads as JSON with structure:
+//     {
+//       "object": "whatsapp_business_account",
+//       "entry": [ { "changes": [ ... ] } ]
+//     }
+//
+//   The handler parses the payload, dispatches incoming messages and status
+//   updates, and must respond with HTTP 200 OK within 10 seconds to avoid
+//   Meta retrying delivery.
+type WhatsAppWebhookHandler struct {
+	provider   *whatsapp.WhatsAppProvider
+	waWebhook  *whatsapp.WebhookHandler
+}
+
+// NewWhatsAppWebhookHandler creates a Gin adapter wrapping the WhatsApp
+// sub-package's WebhookHandler. The provider is stored for future use (e.g.
+// health checks or direct API calls) while waWebhook is the core handler that
+// processes verification and event requests.
+func NewWhatsAppWebhookHandler(provider *whatsapp.WhatsAppProvider, waWebhook *whatsapp.WebhookHandler) *WhatsAppWebhookHandler {
+	return &WhatsAppWebhookHandler{
+		provider:  provider,
+		waWebhook: waWebhook,
+	}
+}
+
+// HandleWhatsAppVerification handles GET requests for WhatsApp Cloud API
+// webhook verification. Meta sends this request during initial webhook setup
+// and periodic re-verification. It delegates to the underlying
+// waWebhook.HandleVerification method which validates hub.verify_token and
+// echoes hub.challenge on success.
+//
+// Expected Gin route: GET /webhooks/whatsapp/:phone_number
+func (h *WhatsAppWebhookHandler) HandleWhatsAppVerification(c *gin.Context) {
+	h.waWebhook.HandleVerification(c)
+}
+
+// HandleWhatsAppWebhook handles POST requests carrying WhatsApp Cloud API
+// event payloads (messages, status updates, template events, etc.). It
+// delegates to the underlying waWebhook.HandleWebhookEvent method which
+// parses the JSON body and dispatches events to the appropriate processor.
+//
+// The endpoint must respond with HTTP 200 OK within 10 seconds; Meta retries
+// delivery on timeout or non-200 responses.
+//
+// Expected Gin route: POST /webhooks/whatsapp/:phone_number
+func (h *WhatsAppWebhookHandler) HandleWhatsAppWebhook(c *gin.Context) {
+	h.waWebhook.HandleWebhookEvent(c)
+}