Skip to main content

WhatsApp Webhook Meta Setup

Audience: external (Meta vendor configuration). Written in English — sibling docs in this folder (architecture.md, deploy-runbook.md, extraction-plan.md, whatsapp-service-status.md) are in Bahasa Indonesia for internal team use. Indonesian translation tracked at merchant_docs/docs/i18n/id/services/whatsapp/webhook-meta-setup.md.

This document describes the steps to set up the Meta Cloud API webhook for services/whatsapp_service.

Goal​

The Meta webhook is used to deliver WhatsApp delivery status into:

  • notification.whatsapp_delivery_events
  • notification.whatsapp_messages.delivery_status

The service endpoints used:

  • GET /webhooks/whatsapp/status
  • POST /webhooks/whatsapp/status

Prerequisites​

  • whatsapp-service is running
  • a public domain for the service is available
  • migration 032_create_notification_whatsapp_tables.sql has been run
  • the production env is correct:
    • WHATSAPP_PROVIDER=meta-cloud-api
    • WHATSAPP_BASE_URL=https://graph.facebook.com/v23.0
    • WHATSAPP_API_KEY=...
    • WHATSAPP_PHONE_NUMBER_ID=...
    • WHATSAPP_VERIFY_TOKEN=...

Webhook URL​

Use the public URL:

https://<public-domain>/webhooks/whatsapp/status

Example:

https://wa.kesles.com/webhooks/whatsapp/status

Verify Token​

The verify token value in Meta must match:

WHATSAPP_VERIFY_TOKEN

When Meta calls:

GET /webhooks/whatsapp/status?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...

the service will:

  • check hub.verify_token
  • echo back hub.challenge

Setup Steps in Meta​

  1. open the Meta App Dashboard
  2. select the WhatsApp product
  3. open the webhook / configuration menu
  4. fill in the callback URL:
https://<public-domain>/webhooks/whatsapp/status
  1. fill in the verify token:
<the WHATSAPP_VERIFY_TOKEN value>
  1. click verify and save
  2. subscribe the field:
    • messages

Payloads Processed​

The service processes the nested status payload from Meta, in particular:

  • sent
  • delivered
  • read
  • failed

Current mapping:

  • sent -> sent
  • delivered -> delivered
  • read -> read
  • failed -> failed

Verification After Setup​

  1. trigger an OTP from the application or API
  2. check notification.whatsapp_messages
  3. confirm provider_message_id is populated
  4. wait for the Meta callback
  5. check notification.whatsapp_delivery_events
  6. confirm delivery_status on the message changes accordingly

See the document:

  • WhatsApp Verification Checklist

Troubleshooting​

Verify fails​

Check:

  • WHATSAPP_VERIFY_TOKEN in the service env
  • the registered webhook URL
  • the service is actually publicly reachable
  • the reverse proxy does not block GET /webhooks/whatsapp/status

Callback does not arrive​

Check:

  • the messages field is subscribed
  • the public domain is correct
  • TLS/HTTPS is valid
  • service logs do not show 4xx/5xx

Delivery event is empty​

Check:

  • provider_message_id on notification.whatsapp_messages
  • the Meta status payload actually carries statuses[].id
  • the messages event is actually being sent by Meta