feat(whatsapp): add webhook registration and status endpoints (#13551)

## Description Adds webhook configuration management for WhatsApp Cloud API channels, allowing administrators to check webhook status and register webhooks directly from Chatwoot without accessing Meta Business Manager. ## Type of change - [ ] New feature (non-breaking change which adds functionality) ## Screenshots <img width="1130" height="676" alt="Screenshot 2026-03-05 at 7 04 18 PM" src="https://github.com/user-attachments/assets/f5dcd9dd-8827-42c5-a52b-1024012703c2" /> <img width="1101" height="651" alt="Screenshot 2026-03-05 at 7 04 29 PM" src="https://github.com/user-attachments/assets/e0bd59f9-2a90-4f24-87c0-b79f21e721ee" /> ## Checklist: - [ ] My code follows the style guidelines of this project - [ ] I have performed a self-review of my code - [ ] I have commented on my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes - [ ] Any dependent changes have been merged and published in downstream modules --------- Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>
2026-03-16 12:48:16 +05:30
parent 28bf9fa5f9
commit a452ce9e84
9 changed files with 194 additions and 45 deletions
--- a/app/controllers/api/v1/accounts/concerns/whatsapp_health_management.rb
+++ b/app/controllers/api/v1/accounts/concerns/whatsapp_health_management.rb
@@ -0,0 +1,55 @@
+module Api::V1::Accounts::Concerns::WhatsappHealthManagement
+  extend ActiveSupport::Concern
+
+  included do
+    skip_before_action :check_authorization, only: [:health, :register_webhook]
+    before_action :check_admin_authorization?, only: [:register_webhook]
+    before_action :validate_whatsapp_cloud_channel, only: [:health, :register_webhook]
+  end
+
+  def sync_templates
+    return render status: :unprocessable_entity, json: { error: 'Template sync is only available for WhatsApp channels' } unless whatsapp_channel?
+
+    trigger_template_sync
+    render status: :ok, json: { message: 'Template sync initiated successfully' }
+  rescue StandardError => e
+    render status: :internal_server_error, json: { error: e.message }
+  end
+
+  def health
+    health_data = Whatsapp::HealthService.new(@inbox.channel).fetch_health_status
+    render json: health_data
+  rescue StandardError => e
+    Rails.logger.error "[INBOX HEALTH] Error fetching health data: #{e.message}"
+    render json: { error: e.message }, status: :unprocessable_entity
+  end
+
+  def register_webhook
+    Whatsapp::WebhookSetupService.new(@inbox.channel).register_callback
+
+    render json: { message: 'Webhook registered successfully' }, status: :ok
+  rescue StandardError => e
+    Rails.logger.error "[INBOX WEBHOOK] Webhook registration failed: #{e.message}"
+    render json: { error: e.message }, status: :unprocessable_entity
+  end
+
+  private
+
+  def validate_whatsapp_cloud_channel
+    return if @inbox.channel.is_a?(Channel::Whatsapp) && @inbox.channel.provider == 'whatsapp_cloud'
+
+    render json: { error: 'Health data only available for WhatsApp Cloud API channels' }, status: :bad_request
+  end
+
+  def whatsapp_channel?
+    @inbox.whatsapp? || (@inbox.twilio? && @inbox.channel.whatsapp?)
+  end
+
+  def trigger_template_sync
+    if @inbox.whatsapp?
+      Channels::Whatsapp::TemplatesSyncJob.perform_later(@inbox.channel)
+    elsif @inbox.twilio? && @inbox.channel.whatsapp?
+      Channels::Twilio::TemplatesSyncJob.perform_later(@inbox.channel)
+    end
+  end
+end
--- a/app/controllers/api/v1/accounts/inboxes_controller.rb
+++ b/app/controllers/api/v1/accounts/inboxes_controller.rb
@@ -4,8 +4,9 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
  before_action :fetch_agent_bot, only: [:set_agent_bot]
  before_action :validate_limit, only: [:create]
  # we are already handling the authorization in fetch inbox
-  before_action :check_authorization, except: [:show, :health]
-  before_action :validate_whatsapp_cloud_channel, only: [:health]
+  before_action :check_authorization, except: [:show]
+
+  include Api::V1::Accounts::Concerns::WhatsappHealthManagement

  def index
    @inboxes = policy_scope(Current.account.inboxes.order_by_name.includes(:channel, { avatar_attachment: [:blob] }))
@@ -70,23 +71,6 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
    render status: :ok, json: { message: I18n.t('messages.inbox_deletetion_response') }
  end

-  def sync_templates
-    return render status: :unprocessable_entity, json: { error: 'Template sync is only available for WhatsApp channels' } unless whatsapp_channel?
-
-    trigger_template_sync
-    render status: :ok, json: { message: 'Template sync initiated successfully' }
-  rescue StandardError => e
-    render status: :internal_server_error, json: { error: e.message }
-  end
-
-  def health
-    health_data = Whatsapp::HealthService.new(@inbox.channel).fetch_health_status
-    render json: health_data
-  rescue StandardError => e
-    Rails.logger.error "[INBOX HEALTH] Error fetching health data: #{e.message}"
-    render json: { error: e.message }, status: :unprocessable_entity
-  end
-
  private

  def fetch_inbox
@@ -98,12 +82,6 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
    @agent_bot = AgentBot.find(params[:agent_bot]) if params[:agent_bot]
  end

-  def validate_whatsapp_cloud_channel
-    return if @inbox.channel.is_a?(Channel::Whatsapp) && @inbox.channel.provider == 'whatsapp_cloud'
-
-    render json: { error: 'Health data only available for WhatsApp Cloud API channels' }, status: :bad_request
-  end
-
  def create_channel
    return unless allowed_channel_types.include?(permitted_params[:channel][:type])

@@ -200,18 +178,6 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
  def get_channel_attributes(channel_type)
    channel_type.constantize.const_defined?(:EDITABLE_ATTRS) ? channel_type.constantize::EDITABLE_ATTRS.presence : []
  end
-
-  def whatsapp_channel?
-    @inbox.whatsapp? || (@inbox.twilio? && @inbox.channel.whatsapp?)
-  end
-
-  def trigger_template_sync
-    if @inbox.whatsapp?
-      Channels::Whatsapp::TemplatesSyncJob.perform_later(@inbox.channel)
-    elsif @inbox.twilio? && @inbox.channel.whatsapp?
-      Channels::Twilio::TemplatesSyncJob.perform_later(@inbox.channel)
-    end
-  end
 end

 Api::V1::Accounts::InboxesController.prepend_mod_with('Api::V1::Accounts::InboxesController')
--- a/app/javascript/dashboard/api/inboxHealth.js
+++ b/app/javascript/dashboard/api/inboxHealth.js
@@ -9,6 +9,10 @@ class InboxHealthAPI extends ApiClient {
  getHealthStatus(inboxId) {
    return axios.get(`${this.url}/${inboxId}/health`);
  }
+
+  registerWebhook(inboxId) {
+    return axios.post(`${this.url}/${inboxId}/register_webhook`);
+  }
 }

 export default new InboxHealthAPI();
--- a/app/javascript/dashboard/i18n/locale/en/inboxMgmt.json
+++ b/app/javascript/dashboard/i18n/locale/en/inboxMgmt.json
@@ -685,6 +685,16 @@
          "SANDBOX": "Sandbox",
          "LIVE": "Live"
        }
+      },
+      "WEBHOOK": {
+        "TITLE": "Webhook Configuration",
+        "DESCRIPTION": "Webhook URL is required for your WhatsApp Business Account to receive messages from customers",
+        "ACTION_REQUIRED": "Webhook not configured",
+        "REGISTER_BUTTON": "Register Webhook",
+        "REGISTER_SUCCESS": "Webhook registered successfully",
+        "REGISTER_ERROR": "Failed to register webhook. Please try again.",
+        "CONFIGURED_SUCCESS": "Webhook configured successfully",
+        "URL_MISMATCH": "Webhook URL mismatch"
      }
    },
    "SETTINGS": "Settings",
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/Settings.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/Settings.vue
@@ -99,6 +99,7 @@ export default {
      healthData: null,
      isLoadingHealth: false,
      healthError: null,
+      isRegisteringWebhook: false,
      widgetBubblePosition: 'right',
      widgetBubbleType: 'standard',
      widgetBubbleLauncherTitle: '',
@@ -424,6 +425,23 @@ export default {
        this.isLoadingHealth = false;
      }
    },
+    async registerWebhook() {
+      if (!this.inbox) return;
+
+      try {
+        this.isRegisteringWebhook = true;
+        await InboxHealthAPI.registerWebhook(this.inbox.id);
+        useAlert(this.$t('INBOX_MGMT.ACCOUNT_HEALTH.WEBHOOK.REGISTER_SUCCESS'));
+        await this.fetchHealthData();
+      } catch (error) {
+        useAlert(
+          error.message ||
+            this.$t('INBOX_MGMT.ACCOUNT_HEALTH.WEBHOOK.REGISTER_ERROR')
+        );
+      } finally {
+        this.isRegisteringWebhook = false;
+      }
+    },
    handleFeatureFlag(e) {
      this.selectedFeatureFlags = this.toggleInput(
        this.selectedFeatureFlags,
@@ -1162,7 +1180,11 @@ export default {
          <BotConfiguration :inbox="inbox" />
        </div>
        <div v-if="selectedTabKey === 'whatsapp-health'">
-          <AccountHealth :health-data="healthData" />
+          <AccountHealth
+            :health-data="healthData"
+            :is-registering-webhook="isRegisteringWebhook"
+            @register-webhook="registerWebhook"
+          />
        </div>
      </div>
    </section>
--- a/app/javascript/dashboard/routes/dashboard/settings/inbox/components/AccountHealth.vue
+++ b/app/javascript/dashboard/routes/dashboard/settings/inbox/components/AccountHealth.vue
@@ -10,8 +10,14 @@ const props = defineProps({
    type: Object,
    default: null,
  },
+  isRegisteringWebhook: {
+    type: Boolean,
+    default: false,
+  },
 });

+const emit = defineEmits(['registerWebhook']);
+
 const { t } = useI18n();

 const QUALITY_COLORS = {
@@ -133,6 +139,28 @@ const formatModeDisplay = mode =>
 const getModeStatusTextColor = mode => MODE_COLORS[mode] || 'text-n-slate-12';

 const getStatusTextColor = status => STATUS_COLORS[status] || 'text-n-slate-12';
+
+const showWebhookSection = computed(
+  () => props.healthData?.webhook_configuration !== undefined
+);
+
+const webhookUrl = computed(
+  () =>
+    props.healthData?.webhook_configuration?.whatsapp_business_account ||
+    props.healthData?.webhook_configuration?.application
+);
+
+const webhookConfigured = computed(() => !!webhookUrl.value);
+
+const webhookUrlMismatch = computed(
+  () =>
+    webhookConfigured.value &&
+    webhookUrl.value !== props.healthData?.expected_webhook_url
+);
+
+const handleRegisterWebhook = () => {
+  emit('registerWebhook');
+};
 </script>

 <template>
@@ -211,6 +239,55 @@ const getStatusTextColor = status => STATUS_COLORS[status] || 'text-n-slate-12';
            }}</span>
          </div>
        </div>
+
+        <!-- Webhook configuration card -->
+        <div
+          v-if="showWebhookSection"
+          class="flex flex-col gap-2 p-4 rounded-lg border border-n-weak bg-n-solid-1"
+        >
+          <div class="flex gap-2 items-center">
+            <span class="text-body-main font-medium text-n-slate-11">
+              {{ t('INBOX_MGMT.ACCOUNT_HEALTH.WEBHOOK.TITLE') }}
+            </span>
+            <Icon
+              v-tooltip.top="t('INBOX_MGMT.ACCOUNT_HEALTH.WEBHOOK.DESCRIPTION')"
+              icon="i-lucide-info"
+              class="flex-shrink-0 w-4 h-4 cursor-help text-n-slate-9"
+            />
+          </div>
+          <div class="flex items-center justify-between gap-3">
+            <span
+              v-if="webhookConfigured && !webhookUrlMismatch"
+              class="inline-flex items-center gap-1.5 px-2 py-0.5 min-h-6 text-label-small rounded-md bg-n-alpha-2 text-n-teal-11"
+            >
+              <Icon icon="i-lucide-check-circle" class="w-3.5 h-3.5" />
+              {{ t('INBOX_MGMT.ACCOUNT_HEALTH.WEBHOOK.CONFIGURED_SUCCESS') }}
+            </span>
+            <span
+              v-else
+              class="inline-flex items-center gap-1.5 px-2 py-0.5 min-h-6 text-label-small rounded-md bg-n-alpha-2 text-n-amber-11"
+            >
+              <Icon icon="i-lucide-alert-triangle" class="w-3.5 h-3.5" />
+              {{
+                webhookUrlMismatch
+                  ? t('INBOX_MGMT.ACCOUNT_HEALTH.WEBHOOK.URL_MISMATCH')
+                  : t('INBOX_MGMT.ACCOUNT_HEALTH.WEBHOOK.ACTION_REQUIRED')
+              }}
+            </span>
+            <ButtonV4
+              v-if="!webhookConfigured || webhookUrlMismatch"
+              sm
+              solid
+              blue
+              :loading="isRegisteringWebhook"
+              :disabled="isRegisteringWebhook"
+              class="flex-shrink-0"
+              @click="handleRegisterWebhook"
+            >
+              {{ t('INBOX_MGMT.ACCOUNT_HEALTH.WEBHOOK.REGISTER_BUTTON') }}
+            </ButtonV4>
+          </div>
+        </div>
      </div>

      <div v-else class="pt-8">
--- a/app/services/whatsapp/health_service.rb
+++ b/app/services/whatsapp/health_service.rb
@@ -39,11 +39,11 @@ class Whatsapp::HealthService

  def health_fields
    %w[
+      id
      quality_rating
      messaging_limit_tier
      code_verification_status
      account_mode
-      id
      display_phone_number
      name_status
      verified_name
@@ -68,6 +68,7 @@ class Whatsapp::HealthService

  def format_health_response(response)
    {
+      id: response['id'],
      display_phone_number: response['display_phone_number'],
      verified_name: response['verified_name'],
      name_status: response['name_status'],
@@ -75,10 +76,20 @@ class Whatsapp::HealthService
      messaging_limit_tier: response['messaging_limit_tier'],
      account_mode: response['account_mode'],
      code_verification_status: response['code_verification_status'],
+      webhook_configuration: response['webhook_configuration'],
+      expected_webhook_url: build_expected_webhook_url,
      throughput: response['throughput'],
      last_onboarded_time: response['last_onboarded_time'],
      platform_type: response['platform_type'],
+      certificate: response['certificate'],
      business_id: @channel.provider_config['business_account_id']
    }
  end
+
+  def build_expected_webhook_url
+    frontend_url = ENV.fetch('FRONTEND_URL', nil)
+    return nil if frontend_url.blank?
+
+    "#{frontend_url}/webhooks/whatsapp/#{@channel.phone_number}"
+  end
 end
--- a/app/services/whatsapp/webhook_setup_service.rb
+++ b/app/services/whatsapp/webhook_setup_service.rb
@@ -1,9 +1,9 @@
 class Whatsapp::WebhookSetupService
-  def initialize(channel, waba_id, access_token)
+  def initialize(channel, waba_id = nil, access_token = nil)
    @channel = channel
-    @waba_id = waba_id
-    @access_token = access_token
-    @api_client = Whatsapp::FacebookApiClient.new(access_token)
+    @waba_id = waba_id || channel.provider_config['business_account_id']
+    @access_token = access_token || channel.provider_config['api_key']
+    @api_client = Whatsapp::FacebookApiClient.new(@access_token)
  end

  def perform
@@ -17,6 +17,11 @@ class Whatsapp::WebhookSetupService
    setup_webhook
  end

+  def register_callback
+    validate_parameters!
+    setup_webhook
+  end
+
  private

  def validate_parameters!
@@ -33,8 +38,6 @@ class Whatsapp::WebhookSetupService
    store_pin(pin)
  rescue StandardError => e
    Rails.logger.warn("[WHATSAPP] Phone registration failed but continuing: #{e.message}")
-    # Continue with webhook setup even if registration fails
-    # This is just a warning, not a blocking error
  end

  def fetch_or_create_pin
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -218,6 +218,7 @@ Rails.application.routes.draw do
            delete :avatar, on: :member
            post :sync_templates, on: :member
            get :health, on: :member
+            post :register_webhook, on: :member
            if ChatwootApp.enterprise?
              resource :conference, only: %i[create destroy], controller: 'conference' do
                get :token, on: :member