Skip to main content

WhatsApp Service Refactor Plan

Status: 🟢 Stage 1–5 DONE (2026-05-19). Stage 6 webhook delivery ✅ DONE 2026-05-25 — nginx proxy ke whatsapp_service:8091, core_api webhook handler + 5 legacy packages dihapus. Stage 7 retry policy belum mulai.

Owner: Backend Lead

This document breaks down the steps to refactor the WhatsApp domain so it can be safely moved from merchant_core_api into a separate service.

Current State (2026-05-19)​

  • ✅ Outbound (OTP, text message) sudah lewat services/whatsapp_service via HTTP. merchant_core_api/internal/whatsapp/client.go (direct Facebook Graph API) sudah dihapus 2026-05-19.
  • ✅ services/whatsapp_service operational dengan 7 endpoint (/health, /ready, /internal/whatsapp/otp, /internal/whatsapp/messages, /internal/whatsapp/messages/{id}, /internal/whatsapp/template, /webhooks/whatsapp/status).
  • ✅ DB schema notification.whatsapp_* aktif (migration 032).
  • ✅ Webhook inbound POST /merchant/api/webhook/whatsapp DONE 2026-05-25 — nginx proxy langsung ke whatsapp_service:8091. File + 5 legacy packages (handler.go, events.go, parser.go, signature.go, verifier.go) di core_api sudah dihapus.
  • ❌ Retry policy belum implementasi di whatsapp_service.

End State​

  • merchant_core_api becomes the internal client for WhatsApp
  • services/whatsapp_service becomes the delivery engine
  • the WhatsApp database log moves to the notification schema

Refactor Stages​

1. Freeze Contract ✅ DONE​

  • inventory all active WhatsApp use cases
  • inventory request/response contracts
  • define stable internal endpoints

2. Extract Provider Logic ✅ DONE​

  • move the provider adapter into a new package/service
  • do not change the business flow yet

3. Introduce WhatsApp Service ✅ DONE​

  • create the new binary/service
  • add /health
  • add /internal/whatsapp/otp
  • add /internal/whatsapp/messages

4. Introduce Notification Schema ✅ DONE​

  • run migration 032_create_notification_whatsapp_tables.sql
  • start recording messages, attempts, and delivery events

5. Switch Core API ✅ DONE (2026-05-19)​

  • ✅ Direct provider path (client.go, payload.go, transport.go) di merchant_core_api/internal/whatsapp/ dihapus
  • ✅ NewSender factory di-simplify — selalu return serviceSender (HTTP ke whatsapp_service)
  • ✅ Config field Facebook Graph (WhatsAppAccessToken, WhatsAppPhoneNumberID, WhatsAppAPIVersion, WhatsAppTemplateName, WhatsAppTemplateLocale, WhatsAppTransport) dihapus
  • ✅ OTP challenge logic tetap di core_api

6. Enable Webhook Delivery ✅ DONE 2026-05-25​

  • ✅ Provider callbacks sekarang landing di whatsapp_service:8091 via nginx proxy /merchant/api/webhook/whatsapp → whatsapp_service:8091
  • ✅ core_api webhook handler + 5 legacy packages (handler.go, events.go, parser.go, signature.go, verifier.go) DIHAPUS
  • ✅ GET /internal/whatsapp/messages/{id} sudah expose di whatsapp_service untuk audit

7. Add Retry Policy ❌ NOT STARTED​

  • retry on failed status
  • dedup for provider webhooks
  • exponential backoff if needed

Acceptance Criteria​

  • ✅ OTP can still be sent
  • ✅ the core API does not need to know provider details
  • ✅ every message has an audit trail
  • ✅ delivery events can be traced from a business reference
  • ✅ provider failures do not break the main auth/merchant flow

Cutover Strategy (historical — done)​

Feature flag WHATSAPP_TRANSPORT di-pakai untuk gradual rollout. Setelah Stage 5 done (2026-05-19), flag dihapus karena direct path code sudah tidak ada — production permanen pakai service path.