Skip to main content

Integrasi WhatsApp Meta Cloud API & Webhook

Platform mengintegrasikan WhatsApp Business Platform Cloud API resmi dari Meta (bukan otomatisasi WhatsApp Web scraping/unofficial) untuk menjamin keandalan pengiriman pesan dan kepatuhan terhadap kebijakan Meta.

1. Arsitektur Komunikasi Meta​

sequenceDiagram
    autonumber
    actor Admin as Admin Organisasi
    participant Backend as Backend Codeverta
    participant Meta as Meta Graph API (v23.0)
    participant Guest as WhatsApp Tamu

    Admin->>Backend: Input WABA ID, Phone Number ID, Token
    Backend->>Meta: GET /{phone-number-id} (Verifikasi Live)
    Meta-->>Backend: Status Valid & Metadata Nomor
    Backend->>Backend: Enkripsi Token (AES-256-GCM) & Simpan ke DB

    Admin->>Backend: Sync Templates
    Backend->>Meta: GET /{waba-id}/message_templates
    Meta-->>Backend: Daftar Template APPROVED
    Backend->>Backend: Upsert Template ke Database Organisasi

    Admin->>Backend: Kirim Undangan via Template
    Backend->>Meta: POST /{phone-number-id}/messages
    Meta-->>Backend: Return Provider Message ID (wamid...)
    Meta->>Guest: Kirim Pesan ke Aplikasi WhatsApp Tamu

    Guest-->>Meta: Status Update (Delivered / Read)
    Meta->>Backend: POST /api/integrations/whatsapp/webhook
    Backend->>Backend: Validasi Signature X-Hub-Signature-256 (HMAC-SHA256)
    Backend->>Backend: Update Status Pesan ke Database

2. Parameter Kredensial yang Dibutuhkan​

Untuk menghubungkan akun WhatsApp Business organisasi, sistem membutuhkan:

  • WhatsApp Business Account ID (WABA ID): ID unik akun WABA di Business Manager Meta.
  • Phone Number ID: ID unik nomor telepon yang terdaftar pada Cloud API (bukan nomor telepon fisik).
  • Permanent Access Token: Token pengguna sistem (System User Token) dengan scope izin:
    • whatsapp_business_messaging
    • whatsapp_business_management
  • Graph API Version: Versi Meta Graph API yang digunakan (default: v23.0).

3. Keamanan & Enkripsi Kredensial​

  1. Enkripsi AES-GCM: Token akses permanen dienkripsi menggunakan algoritma AES-256-GCM sebelum disimpan ke kolom database PostgreSQL.
  2. Kunci Enkripsi Terpisah: Kunci enkripsi (DB_ENCRYPTION_KEY dan DB_HMAC_KEY) dikelola melalui environment variables dan tidak pernah di-hardcode di kode sumber.
  3. Penyembunyian Data Rahasia: Token yang telah tersimpan tidak pernah dikembalikan ke antarmuka frontend/API response (selalu dimasking).

4. Konfigurasi Endpoint Webhook Meta​

Untuk menerima pembaruan status pesan (SENT, DELIVERED, READ, FAILED):

URL Webhook Publik​

https://api.codeverta.com/api/integrations/whatsapp/webhook

Verifikasi Webhook Handshake (GET)​

Meta akan memverifikasi endpoint dengan mengirimkan parameter query:

  • hub.mode=subscribe
  • hub.verify_token=<WHATSAPP_WEBHOOK_VERIFY_TOKEN>
  • hub.challenge=<challenge_code>

Backend memvalidasi kesesuaian hub.verify_token dengan environment lokal dan mengembalikan hub.challenge dengan status HTTP 200 OK.

Validasi Keamanan Signature Webhook (POST)​

Setiap payload event webhook yang dikirimkan oleh Meta menyertakan header:

X-Hub-Signature-256: sha256=<hmac_hash>

Backend menghitung HMAC-SHA256 dari seluruh raw request body menggunakan WHATSAPP_APP_SECRET. Request akan ditolak dengan kode 401 Unauthorized jika signature tidak cocok.