From 6928f14a762e5ae40b74d5901fb7685c46ac4ee2 Mon Sep 17 00:00:00 2001
From: Gabor Barany <23645175+gbarany@users.noreply.github.com>
Date: Tue, 21 Apr 2026 10:44:25 +0100
Subject: [PATCH 1/7] fix: Validate Twilio webhook signatures
 (X-Twilio-Signature) (#13638)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #13619

## Summary

- Add `TwilioSignatureVerifyConcern` that validates the
`X-Twilio-Signature` header using `Twilio::Security::RequestValidator`
(already bundled via `twilio-ruby` gem)
- Include the concern in `Twilio::CallbackController` and
`Twilio::DeliveryStatusController` — both endpoints were previously
accepting requests from any source with no authentication
- Channels using API key authentication (`api_key_sid` present) skip
validation with a warning log, since Twilio signs with the account auth
token which isn't stored for those channels

## How it works

1. `before_action` looks up the `Channel::TwilioSms` from request params
(`MessagingServiceSid` or `AccountSid` + phone number)
2. Validates the HMAC-SHA1 signature using the channel's auth token
3. Returns `403 Forbidden` if signature is invalid, missing, or channel
not found
4. Handles reverse proxy URL reconstruction via `X-Forwarded-Proto`
header

Follows the same pattern used by `Webhooks::ShopifyController` and
`Webhooks::TiktokController`.

## Test plan

- [x] Valid signature → 204 No Content, job enqueued
- [x] Invalid signature → 403 Forbidden, job not enqueued
- [x] Missing signature header → 403 Forbidden
- [x] Channel not found → 403 Forbidden
- [x] API key channel → skips validation, job enqueued (with warning
log)
- [x] MessagingServiceSid lookup → validates and enqueues
- [x] All existing Twilio service/job specs pass (99 examples, 0
failures)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>
Co-authored-by: Sojan Jose <sojan@pepalo.com>
---
 .../twilio_signature_verify_concern.rb        |  88 ++++++++++
 app/controllers/twilio/callback_controller.rb |   2 +
 .../twilio/delivery_status_controller.rb      |   6 +
 .../twilio/callbacks_controller_spec.rb       | 151 +++++++++++++++++-
 .../twilio/delivery_status_controller_spec.rb | 125 ++++++++++++++-
 5 files changed, 356 insertions(+), 16 deletions(-)
 create mode 100644 app/controllers/concerns/twilio_signature_verify_concern.rb

diff --git a/app/controllers/concerns/twilio_signature_verify_concern.rb b/app/controllers/concerns/twilio_signature_verify_concern.rb
new file mode 100644
index 000000000..b7a4754a4
--- /dev/null
+++ b/app/controllers/concerns/twilio_signature_verify_concern.rb
@@ -0,0 +1,88 @@
+module TwilioSignatureVerifyConcern
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :verify_twilio_signature!
+  end
+
+  private
+
+  def verify_twilio_signature!
+    channel = find_twilio_channel
+    return log_and_reject_missing_channel if channel.blank?
+    return if channel.api_key_sid.present? && log_api_key_skip(channel)
+
+    head :forbidden unless valid_signature?(channel)
+  end
+
+  def log_and_reject_missing_channel
+    Rails.logger.warn(
+      '[TWILIO] Channel not found for webhook ' \
+      "account_sid=#{params[:AccountSid]} messaging_service_sid=#{params[:MessagingServiceSid]} " \
+      "to=#{params[:To]} from=#{params[:From]}"
+    )
+    head :forbidden
+  end
+
+  def log_api_key_skip(channel)
+    Rails.logger.warn(
+      '[TWILIO] Signature validation skipped: channel uses API key authentication. ' \
+      "account_sid=#{params[:AccountSid]} channel_id=#{channel.id}"
+    )
+  end
+
+  def valid_signature?(channel)
+    signature = request.headers['X-Twilio-Signature']
+    if signature.blank?
+      Rails.logger.warn("[TWILIO] Missing X-Twilio-Signature header account_sid=#{params[:AccountSid]}")
+      return false
+    end
+
+    validator = Twilio::Security::RequestValidator.new(channel.auth_token)
+    request_url = reconstruct_url
+    return true if validator.validate(request_url, request.request_parameters, signature)
+
+    Rails.logger.warn(
+      '[TWILIO] Signature validation failed ' \
+      "account_sid=#{params[:AccountSid]} channel_id=#{channel.id} url=#{request_url} ip=#{request.remote_ip}"
+    )
+    false
+  end
+
+  def find_twilio_channel
+    if params[:MessagingServiceSid].present?
+      channel = ::Channel::TwilioSms.find_by(messaging_service_sid: params[:MessagingServiceSid])
+      return channel if channel.present? && (params[:AccountSid].blank? || channel.account_sid == params[:AccountSid])
+
+      return nil
+    end
+    return if params[:AccountSid].blank?
+
+    find_channel_by_phone_number
+  end
+
+  def find_channel_by_phone_number
+    channel_lookup_phone_numbers.each do |phone|
+      channel = ::Channel::TwilioSms.find_by(account_sid: params[:AccountSid], phone_number: phone)
+      return channel if channel
+    end
+    nil
+  end
+
+  def channel_lookup_phone_numbers
+    [params[:To], params[:From]].compact_blank
+  end
+
+  def reconstruct_url
+    url = request.original_url
+    url = url.sub('http://', 'https://') if url.start_with?('http://') && https_request?
+    url
+  end
+
+  def https_request?
+    return true if request.ssl?
+
+    forwarded_proto = request.headers['X-Forwarded-Proto'].to_s.split(',').map(&:strip).find(&:present?)
+    forwarded_proto&.casecmp?('https')
+  end
+end
diff --git a/app/controllers/twilio/callback_controller.rb b/app/controllers/twilio/callback_controller.rb
index d607ba151..9b42cd034 100644
--- a/app/controllers/twilio/callback_controller.rb
+++ b/app/controllers/twilio/callback_controller.rb
@@ -1,4 +1,6 @@
 class Twilio::CallbackController < ApplicationController
+  include TwilioSignatureVerifyConcern
+
   def create
     Webhooks::TwilioEventsJob.perform_later(permitted_params.to_unsafe_hash)
 
diff --git a/app/controllers/twilio/delivery_status_controller.rb b/app/controllers/twilio/delivery_status_controller.rb
index 1c756a1c2..8e846a737 100644
--- a/app/controllers/twilio/delivery_status_controller.rb
+++ b/app/controllers/twilio/delivery_status_controller.rb
@@ -1,4 +1,6 @@
 class Twilio::DeliveryStatusController < ApplicationController
+  include TwilioSignatureVerifyConcern
+
   def create
     Webhooks::TwilioDeliveryStatusJob.perform_later(permitted_params.to_unsafe_hash)
 
@@ -18,4 +20,8 @@ class Twilio::DeliveryStatusController < ApplicationController
       :ErrorMessage
     )
   end
+
+  def channel_lookup_phone_numbers
+    [params[:From]].compact_blank
+  end
 end
diff --git a/spec/controllers/twilio/callbacks_controller_spec.rb b/spec/controllers/twilio/callbacks_controller_spec.rb
index d16acf229..09b558096 100644
--- a/spec/controllers/twilio/callbacks_controller_spec.rb
+++ b/spec/controllers/twilio/callbacks_controller_spec.rb
@@ -4,25 +4,160 @@ RSpec.describe 'Twilio::CallbacksController', type: :request do
   include Rails.application.routes.url_helpers
 
   describe 'POST /twilio/callback' do
+    let(:account) { create(:account) }
+    let(:twilio_channel) { create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123') }
     let(:params) do
       {
         'From' => '+1234567890',
-        'To' => '+0987654321',
+        'To' => twilio_channel.phone_number,
         'Body' => 'Test message',
         'AccountSid' => 'AC123',
         'SmsSid' => 'SM123'
       }
     end
 
-    it 'enqueues the Twilio events job' do
-      expect do
-        post twilio_callback_index_url, params: params
-      end.to have_enqueued_job(Webhooks::TwilioEventsJob).with(params)
+    def post_with_signature(url, params:)
+      validator = Twilio::Security::RequestValidator.new(twilio_channel.auth_token)
+      signature = validator.build_signature_for(url, params)
+      post url, params: params, headers: { 'X-Twilio-Signature' => signature }
     end
 
-    it 'returns no content status' do
-      post twilio_callback_index_url, params: params
-      expect(response).to have_http_status(:no_content)
+    context 'with valid signature' do
+      it 'enqueues the Twilio events job' do
+        url = twilio_callback_index_url
+        expect do
+          post_with_signature(url, params: params)
+        end.to have_enqueued_job(Webhooks::TwilioEventsJob)
+      end
+
+      it 'returns no content status' do
+        url = twilio_callback_index_url
+        post_with_signature(url, params: params)
+        expect(response).to have_http_status(:no_content)
+      end
+    end
+
+    context 'with invalid signature' do
+      it 'returns forbidden status' do
+        post twilio_callback_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
+        expect(response).to have_http_status(:forbidden)
+      end
+
+      it 'does not enqueue the job' do
+        expect do
+          post twilio_callback_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
+        end.not_to have_enqueued_job(Webhooks::TwilioEventsJob)
+      end
+    end
+
+    context 'with missing signature header' do
+      it 'returns forbidden status' do
+        post twilio_callback_index_url, params: params
+        expect(response).to have_http_status(:forbidden)
+      end
+    end
+
+    context 'when channel is not found' do
+      it 'returns forbidden status' do
+        post twilio_callback_index_url, params: params.merge('AccountSid' => 'UNKNOWN', 'To' => '+0000000000')
+        expect(response).to have_http_status(:forbidden)
+      end
+    end
+
+    context 'when channel uses API key authentication' do
+      let(:twilio_channel) do
+        create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123', api_key_sid: 'SK123')
+      end
+
+      it 'skips signature validation and enqueues the job' do
+        expect do
+          post twilio_callback_index_url, params: params
+        end.to have_enqueued_job(Webhooks::TwilioEventsJob)
+      end
+    end
+
+    context 'when behind a reverse proxy with X-Forwarded-Proto' do
+      it 'validates signature against the HTTPS URL' do
+        http_url = twilio_callback_index_url
+        https_url = http_url.sub('http://', 'https://')
+        validator = Twilio::Security::RequestValidator.new(twilio_channel.auth_token)
+        signature = validator.build_signature_for(https_url, params)
+        post http_url, params: params, headers: {
+          'X-Twilio-Signature' => signature,
+          'X-Forwarded-Proto' => 'https'
+        }
+        expect(response).to have_http_status(:no_content)
+      end
+
+      it 'validates signature when forwarded proto is a comma-separated chain' do
+        http_url = twilio_callback_index_url
+        https_url = http_url.sub('http://', 'https://')
+        validator = Twilio::Security::RequestValidator.new(twilio_channel.auth_token)
+        signature = validator.build_signature_for(https_url, params)
+        post http_url, params: params, headers: {
+          'X-Twilio-Signature' => signature,
+          'X-Forwarded-Proto' => 'https,http'
+        }
+        expect(response).to have_http_status(:no_content)
+      end
+    end
+
+    context 'with MessagingServiceSid lookup' do
+      let(:twilio_channel) { create(:channel_twilio_sms, account: account, account_sid: 'AC123') }
+      let(:params) do
+        {
+          'From' => '+1234567890',
+          'Body' => 'Test message',
+          'AccountSid' => 'AC123',
+          'SmsSid' => 'SM123',
+          'MessagingServiceSid' => twilio_channel.messaging_service_sid
+        }
+      end
+
+      it 'validates and enqueues the job' do
+        url = twilio_callback_index_url
+        post_with_signature(url, params: params)
+        expect(response).to have_http_status(:no_content)
+      end
+    end
+
+    context 'when MessagingServiceSid is present but does not match a channel' do
+      let(:params) do
+        {
+          'From' => '+1234567890',
+          'To' => twilio_channel.phone_number,
+          'Body' => 'Test message',
+          'AccountSid' => 'AC123',
+          'SmsSid' => 'SM123',
+          'MessagingServiceSid' => 'MG_UNKNOWN'
+        }
+      end
+
+      it 'returns forbidden without falling back to phone number lookup' do
+        url = twilio_callback_index_url
+        post_with_signature(url, params: params)
+        expect(response).to have_http_status(:forbidden)
+      end
+    end
+
+    context 'when MessagingServiceSid matches a channel but AccountSid does not' do
+      let(:other_channel) { create(:channel_twilio_sms, account: account, account_sid: 'AC_OTHER') }
+      let(:params) do
+        {
+          'From' => '+1234567890',
+          'To' => twilio_channel.phone_number,
+          'Body' => 'Test message',
+          'AccountSid' => 'AC123',
+          'SmsSid' => 'SM123',
+          'MessagingServiceSid' => other_channel.messaging_service_sid
+        }
+      end
+
+      it 'returns forbidden without falling back to phone number lookup' do
+        url = twilio_callback_index_url
+        post_with_signature(url, params: params)
+        expect(response).to have_http_status(:forbidden)
+      end
     end
   end
 end
diff --git a/spec/controllers/twilio/delivery_status_controller_spec.rb b/spec/controllers/twilio/delivery_status_controller_spec.rb
index fc21f8f94..dc99fdf23 100644
--- a/spec/controllers/twilio/delivery_status_controller_spec.rb
+++ b/spec/controllers/twilio/delivery_status_controller_spec.rb
@@ -4,23 +4,132 @@ RSpec.describe 'Twilio::DeliveryStatusController', type: :request do
   include Rails.application.routes.url_helpers
 
   describe 'POST /twilio/delivery_status' do
+    let(:account) { create(:account) }
+    let(:twilio_channel) { create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123') }
     let(:params) do
       {
         'MessageSid' => 'SM123',
         'MessageStatus' => 'delivered',
-        'AccountSid' => 'AC123'
+        'AccountSid' => 'AC123',
+        'From' => twilio_channel.phone_number
       }
     end
 
-    it 'enqueues the Twilio delivery status job' do
-      expect do
-        post twilio_delivery_status_index_url, params: params
-      end.to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob).with(params)
+    def post_with_signature(url, params:, channel: twilio_channel)
+      validator = Twilio::Security::RequestValidator.new(channel.auth_token)
+      signature = validator.build_signature_for(url, params)
+      post url, params: params, headers: { 'X-Twilio-Signature' => signature }
     end
 
-    it 'returns no content status' do
-      post twilio_delivery_status_index_url, params: params
-      expect(response).to have_http_status(:no_content)
+    context 'with valid signature' do
+      it 'enqueues the delivery status job' do
+        url = twilio_delivery_status_index_url
+        expect do
+          post_with_signature(url, params: params)
+        end.to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
+      end
+
+      it 'returns no content status' do
+        url = twilio_delivery_status_index_url
+        post_with_signature(url, params: params)
+        expect(response).to have_http_status(:no_content)
+      end
+    end
+
+    context 'with invalid signature' do
+      it 'returns forbidden status' do
+        post twilio_delivery_status_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
+        expect(response).to have_http_status(:forbidden)
+      end
+
+      it 'does not enqueue the job' do
+        expect do
+          post twilio_delivery_status_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
+        end.not_to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
+      end
+    end
+
+    context 'with missing signature header' do
+      it 'returns forbidden status' do
+        post twilio_delivery_status_index_url, params: params
+        expect(response).to have_http_status(:forbidden)
+      end
+    end
+
+    context 'when channel uses API key authentication' do
+      let(:twilio_channel) do
+        create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123', api_key_sid: 'SK123')
+      end
+
+      it 'skips signature validation and enqueues the job' do
+        expect do
+          post twilio_delivery_status_index_url, params: params
+        end.to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
+      end
+    end
+
+    context 'with MessagingServiceSid lookup' do
+      let(:twilio_channel) { create(:channel_twilio_sms, account: account, account_sid: 'AC123') }
+      let(:params) do
+        {
+          'MessageSid' => 'SM123',
+          'MessageStatus' => 'delivered',
+          'AccountSid' => 'AC123',
+          'MessagingServiceSid' => twilio_channel.messaging_service_sid
+        }
+      end
+
+      it 'validates and enqueues the job' do
+        url = twilio_delivery_status_index_url
+        post_with_signature(url, params: params)
+        expect(response).to have_http_status(:no_content)
+      end
+    end
+
+    context 'when To does not map to a channel but From does' do
+      let(:params) do
+        {
+          'MessageSid' => 'SM123',
+          'MessageStatus' => 'delivered',
+          'AccountSid' => 'AC123',
+          'To' => '+19999999999',
+          'From' => twilio_channel.phone_number
+        }
+      end
+
+      it 'falls back to From lookup and enqueues the delivery status job' do
+        url = twilio_delivery_status_index_url
+
+        expect do
+          post_with_signature(url, params: params)
+        end.to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
+
+        expect(response).to have_http_status(:no_content)
+      end
+    end
+
+    context 'when To maps to an API-key channel but From maps to a different channel' do
+      let!(:api_key_channel) do
+        create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123', api_key_sid: 'SK123')
+      end
+      let!(:from_channel) { create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123') }
+      let(:params) do
+        {
+          'MessageSid' => 'SM123',
+          'MessageStatus' => 'delivered',
+          'AccountSid' => 'AC123',
+          'To' => api_key_channel.phone_number,
+          'From' => from_channel.phone_number
+        }
+      end
+
+      it 'rejects invalid signatures instead of skipping verification' do
+        expect do
+          post twilio_delivery_status_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
+        end.not_to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
+
+        expect(response).to have_http_status(:forbidden)
+      end
     end
   end
 end

From 6a9c44476e2293542c036bffe845c7bb4160ce47 Mon Sep 17 00:00:00 2001
From: Muhsin Keloth <muhsinkeramam@gmail.com>
Date: Tue, 21 Apr 2026 15:55:12 +0400
Subject: [PATCH 2/7] feat(super-admin): Add push diagnostics tool (#14105)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We're getting many customer reports saying "I'm not getting
notifications." We can't always identify the root cause since there are
multiple points of failure. Added a **Push Diagnostics** tool in Super
Admin to help us investigate mobile/web push issues.

Here's how it works:

- Look up a user by email/ID → see all their registered subscriptions
with device info (iOS/Android, brand, model), token freshness, and
last-updated time
- Send a customizable test push and read the raw FCM/web-push/relay
response to see if the customer is receiving push notifications—if not,
it will show proper errors.
- Delete broken subscriptions so the mobile app re-registers on next
launch
<img width="3816" height="1974" alt="CleanShot 2026-04-20 at 12 56
56@2x"
src="https://github.com/user-attachments/assets/08ecab6f-7ec3-44b3-a114-5e6eb8cf0879"
/>

Fixes https://linear.app/chatwoot/issue/CW-6892/push-diagnostics-tool

---------

Co-authored-by: Muhsin <12408980+muhsin-k@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../push_diagnostics_controller.rb            |  68 +++++++
 .../notification/push_test_service.rb         | 160 +++++++++++++++
 .../application/_navigation.html.erb          |   3 +-
 .../push_diagnostics/show.html.erb            | 190 ++++++++++++++++++
 config/locales/en.yml                         |   6 +
 config/routes.rb                              |   3 +
 lib/chatwoot_hub.rb                           |   8 +-
 7 files changed, 435 insertions(+), 3 deletions(-)
 create mode 100644 app/controllers/super_admin/push_diagnostics_controller.rb
 create mode 100644 app/services/notification/push_test_service.rb
 create mode 100644 app/views/super_admin/push_diagnostics/show.html.erb

diff --git a/app/controllers/super_admin/push_diagnostics_controller.rb b/app/controllers/super_admin/push_diagnostics_controller.rb
new file mode 100644
index 000000000..c33cfdc1e
--- /dev/null
+++ b/app/controllers/super_admin/push_diagnostics_controller.rb
@@ -0,0 +1,68 @@
+class SuperAdmin::PushDiagnosticsController < SuperAdmin::ApplicationController
+  def show
+    @query = params[:user_query].to_s.strip
+    @user = resolve_user(@query)
+    @subscriptions = @user ? @user.notification_subscriptions.order(:id) : []
+    @results = []
+  end
+
+  def create
+    @user = User.find_by(id: params[:user_id])
+    return redirect_to super_admin_push_diagnostics_path, alert: I18n.t('super_admin.push_diagnostics.user_not_found') if @user.nil?
+
+    ids = parsed_subscription_ids
+    if ids.empty?
+      return redirect_to super_admin_push_diagnostics_path(user_query: @user.id),
+                         alert: I18n.t('super_admin.push_diagnostics.no_subscriptions_to_test')
+    end
+
+    run_test_and_render(ids)
+  end
+
+  def destroy_subscriptions
+    user = User.find_by(id: params[:user_id])
+    return redirect_to super_admin_push_diagnostics_path, alert: I18n.t('super_admin.push_diagnostics.user_not_found') if user.nil?
+
+    ids = parsed_subscription_ids
+    if ids.empty?
+      return redirect_to super_admin_push_diagnostics_path(user_query: user.id),
+                         alert: I18n.t('super_admin.push_diagnostics.no_subscriptions_to_delete')
+    end
+
+    deleted_count = user.notification_subscriptions.where(id: ids).destroy_all.size
+    log_super_admin_action("deleted #{deleted_count} subscriptions for user #{user.id}: #{ids}")
+    redirect_to super_admin_push_diagnostics_path(user_query: user.id),
+                notice: I18n.t('super_admin.push_diagnostics.subscriptions_deleted', count: deleted_count)
+  end
+
+  private
+
+  def run_test_and_render(ids)
+    @query = @user.id.to_s
+    @subscriptions = @user.notification_subscriptions.order(:id)
+    @results = Notification::PushTestService.new(
+      user: @user, subscription_ids: ids,
+      title: params[:push_title], body: params[:push_body]
+    ).perform
+
+    log_super_admin_action("test sent for user #{@user.id} subscriptions #{ids}")
+    render :show
+  end
+
+  def log_super_admin_action(message)
+    Rails.logger.info(
+      "[SuperAdmin] push diagnostics #{message} " \
+      "(actor_id=#{current_super_admin&.id}, actor_email=#{current_super_admin&.email})"
+    )
+  end
+
+  def resolve_user(query)
+    return if query.blank?
+
+    query.match?(/\A\d+\z/) ? User.find_by(id: query) : User.from_email(query)
+  end
+
+  def parsed_subscription_ids
+    Array(params[:subscription_ids]).reject(&:blank?).map(&:to_i)
+  end
+end
diff --git a/app/services/notification/push_test_service.rb b/app/services/notification/push_test_service.rb
new file mode 100644
index 000000000..4b2bec177
--- /dev/null
+++ b/app/services/notification/push_test_service.rb
@@ -0,0 +1,160 @@
+class Notification::PushTestService
+  pattr_initialize [:user!, :subscription_ids!, :title, :body]
+
+  DEFAULT_TITLE = '%<installation_name>s notification test'.freeze
+  DEFAULT_BODY = 'This is a test from our team to check notification delivery on your device. No action needed.'.freeze
+
+  def self.default_title
+    format(DEFAULT_TITLE, installation_name: GlobalConfigService.load('INSTALLATION_NAME', 'Chatwoot'))
+  end
+
+  def self.default_body
+    DEFAULT_BODY
+  end
+
+  def perform
+    selected_subscriptions.map { |subscription| test_send(subscription) }
+  end
+
+  private
+
+  def resolved_title
+    title.presence || self.class.default_title
+  end
+
+  def resolved_body
+    body.presence || self.class.default_body
+  end
+
+  def selected_subscriptions
+    user.notification_subscriptions.where(id: subscription_ids).order(:id)
+  end
+
+  def test_send(subscription)
+    if subscription.browser_push?
+      test_browser_push(subscription)
+    elsif subscription.fcm?
+      test_fcm(subscription)
+    else
+      result(subscription, subscription.subscription_type.to_s, :skipped, 'Unknown subscription type')
+    end
+  end
+
+  def test_browser_push(subscription)
+    return result(subscription, 'browser_push', :skipped, 'VAPID keys not configured') unless VapidService.public_key
+
+    WebPush.payload_send(**browser_push_payload(subscription))
+    result(subscription, 'browser_push', :success, 'Web push accepted by endpoint')
+  rescue StandardError => e
+    result(subscription, 'browser_push', :failure, "#{e.class.name}: #{e.message}")
+  end
+
+  def test_fcm(subscription)
+    if firebase_credentials_present?
+      test_fcm_direct(subscription)
+    elsif chatwoot_hub_enabled?
+      test_fcm_via_hub(subscription)
+    else
+      result(subscription, 'fcm', :skipped, 'No Firebase credentials and push relay disabled')
+    end
+  end
+
+  def test_fcm_direct(subscription)
+    fcm_service = Notification::FcmService.new(
+      GlobalConfigService.load('FIREBASE_PROJECT_ID', nil),
+      GlobalConfigService.load('FIREBASE_CREDENTIALS', nil)
+    )
+    response = fcm_service.fcm_client.send_v1(fcm_options(subscription))
+    status_code = response[:status_code].to_i
+    status = status_code.between?(200, 299) ? :success : :failure
+    result(subscription, 'fcm', status, "HTTP #{status_code} — #{response[:body]}")
+  rescue StandardError => e
+    result(subscription, 'fcm', :failure, "#{e.class.name}: #{e.message}")
+  end
+
+  def test_fcm_via_hub(subscription)
+    response = ChatwootHub.send_push_with_response(fcm_options(subscription))
+    result(subscription, 'fcm_via_hub', :success, "HTTP #{response.code} — #{response.body}")
+  rescue RestClient::ExceptionWithResponse => e
+    result(subscription, 'fcm_via_hub', :failure, "HTTP #{e.response&.code} — #{e.response&.body}")
+  rescue StandardError => e
+    result(subscription, 'fcm_via_hub', :failure, "#{e.class.name}: #{e.message}")
+  end
+
+  def firebase_credentials_present?
+    GlobalConfigService.load('FIREBASE_PROJECT_ID', nil) && GlobalConfigService.load('FIREBASE_CREDENTIALS', nil)
+  end
+
+  def chatwoot_hub_enabled?
+    ActiveModel::Type::Boolean.new.cast(ENV.fetch('ENABLE_PUSH_RELAY_SERVER', true))
+  end
+
+  def browser_push_payload(subscription)
+    {
+      message: JSON.generate(
+        title: resolved_title,
+        tag: "super_admin_test_#{Time.zone.now.to_i}",
+        url: ENV.fetch('FRONTEND_URL', 'https://app.chatwoot.com')
+      ),
+      endpoint: subscription.subscription_attributes['endpoint'],
+      p256dh: subscription.subscription_attributes['p256dh'],
+      auth: subscription.subscription_attributes['auth'],
+      vapid: {
+        subject: ENV.fetch('FRONTEND_URL', 'https://app.chatwoot.com'),
+        public_key: VapidService.public_key,
+        private_key: VapidService.private_key
+      },
+      ssl_timeout: 5,
+      open_timeout: 5,
+      read_timeout: 5
+    }
+  end
+
+  def fcm_options(subscription)
+    {
+      'token': subscription.subscription_attributes['push_token'],
+      'data': { payload: { data: { notification: { type: 'test' } } }.to_json },
+      'notification': { title: resolved_title, body: resolved_body },
+      'android': { priority: 'high' },
+      'apns': { payload: { aps: { sound: 'default', category: Time.zone.now.to_i.to_s } } },
+      'fcm_options': { analytics_label: 'SuperAdminTest' }
+    }
+  end
+
+  def result(subscription, type, status, message)
+    attrs = subscription.subscription_attributes || {}
+    {
+      id: subscription.id,
+      type: type.to_s,
+      device: device_label(subscription, attrs),
+      token_tail: token_tail(subscription, attrs),
+      status: status,
+      message: message
+    }
+  end
+
+  def device_label(subscription, attrs)
+    if subscription.browser_push?
+      endpoint_host(attrs['endpoint'].to_s)
+    else
+      attrs['device_id'].present? ? "…#{attrs['device_id'].to_s.last(6)}" : '—'
+    end
+  end
+
+  def endpoint_host(endpoint)
+    return '—' if endpoint.blank?
+
+    URI.parse(endpoint).host.presence || endpoint
+  rescue URI::InvalidURIError
+    endpoint
+  end
+
+  def token_tail(subscription, attrs)
+    if subscription.browser_push?
+      endpoint = attrs['endpoint'].to_s
+      endpoint.present? ? "…#{endpoint.last(6)}" : '—'
+    else
+      attrs['push_token'].present? ? "…#{attrs['push_token'].to_s.last(6)}" : '—'
+    end
+  end
+end
diff --git a/app/views/super_admin/application/_navigation.html.erb b/app/views/super_admin/application/_navigation.html.erb
index 787576d33..da3a024f8 100644
--- a/app/views/super_admin/application/_navigation.html.erb
+++ b/app/views/super_admin/application/_navigation.html.erb
@@ -32,7 +32,7 @@ as defined by the routes in the `admin/` namespace
     <ul class="my-4">
       <%= render partial: "nav_item", locals: { icon: 'icon-grid-line', url: super_admin_root_url, label: 'Dashboard' } %>
       <% Administrate::Namespace.new(namespace).resources.each do |resource| %>
-        <% next if ["account_users", "access_tokens", "installation_configs", "dashboard", "devise/sessions", "app_configs", "instance_statuses", "settings"].include?  resource.resource %>
+        <% next if ["account_users", "access_tokens", "installation_configs", "dashboard", "devise/sessions", "app_configs", "instance_statuses", "settings", "push_diagnostics"].include?  resource.resource %>
         <%= render partial: "nav_item", locals: {
             icon: sidebar_icons[resource.resource.to_sym],
             url: resource_index_route(resource),
@@ -48,6 +48,7 @@ as defined by the routes in the `admin/` namespace
     <ul class="my-4">
       <%= render partial: "nav_item", locals: { icon: 'icon-mist-fill', url: sidekiq_web_url, label: 'Sidekiq Dashboard' } %>
       <%= render partial: "nav_item", locals: { icon: 'icon-health-book-line', url: super_admin_instance_status_url, label: 'Instance Health' } %>
+      <%= render partial: "nav_item", locals: { icon: 'icon-mail-send-fill', url: super_admin_push_diagnostics_url, label: 'Push Diagnostics' } %>
       <%= render partial: "nav_item", locals: { icon: 'icon-dashboard-line', url: '/', label: 'Agent Dashboard' } %>
       <%= render partial: "nav_item", locals: { icon: 'icon-logout-circle-r-line', url: super_admin_logout_url, label: 'Logout' } %>
     </ul>
diff --git a/app/views/super_admin/push_diagnostics/show.html.erb b/app/views/super_admin/push_diagnostics/show.html.erb
new file mode 100644
index 000000000..736a77cd8
--- /dev/null
+++ b/app/views/super_admin/push_diagnostics/show.html.erb
@@ -0,0 +1,190 @@
+<% content_for(:title) do %>Push Diagnostics<% end %>
+
+<header class="main-content__header" role="banner">
+  <h1 class="main-content__page-title" id="page-title">Push Diagnostics</h1>
+</header>
+
+<section class="main-content__body">
+  <p class="text-sm text-slate-600 mb-6">
+    Send a test push notification to a specific user's registered devices to diagnose delivery issues.
+    Results show the raw FCM / Web Push / relay response so you can see exactly what failed.
+  </p>
+
+  <div class="mb-8">
+    <h2 class="text-base font-semibold mb-2">1. Look up user</h2>
+    <%= form_with url: super_admin_push_diagnostics_path, method: :get, local: true, class: 'flex gap-2 items-center' do |f| %>
+      <%= f.text_field :user_query,
+                       value: @query,
+                       placeholder: 'user@example.com or numeric user ID',
+                       class: 'border border-slate-100 p-1.5 rounded-md w-80' %>
+      <%= f.submit 'Look up', class: 'border border-slate-200 bg-slate-50 px-3 py-1.5 rounded-md cursor-pointer' %>
+    <% end %>
+    <% if @query.present? && @user.nil? %>
+      <p class="text-sm text-red-600 mt-2">No user found for "<%= @query %>".</p>
+    <% end %>
+  </div>
+
+  <% if @user %>
+    <div class="mb-6 border border-slate-100 rounded-md p-4 bg-slate-25">
+      <p class="text-sm">
+        <strong><%= @user.name %></strong>
+        &middot; <%= @user.email %>
+        &middot; ID <%= @user.id %>
+      </p>
+      <% if @user.accounts.any? %>
+        <p class="text-xs text-slate-500 mt-1">
+          Accounts:
+          <% @user.accounts.each_with_index do |account, index| %>
+            <%= ', ' if index.positive? %>
+            <%= account.name %> (ID <%= account.id %>)
+          <% end %>
+        </p>
+      <% end %>
+    </div>
+
+    <div class="mb-8">
+      <h2 class="text-base font-semibold mb-2">2. Select subscriptions (<%= @subscriptions.count %>)</h2>
+      <p class="text-xs text-amber-700 mb-3">
+        ⚠️ This sends a real push to every selected device. Use only when diagnosing a reported issue.
+      </p>
+
+      <% if @subscriptions.empty? %>
+        <p class="text-sm text-slate-600">This user has no push subscriptions registered.</p>
+      <% else %>
+        <%= form_with url: super_admin_push_diagnostics_path, method: :post, local: true do |f| %>
+          <%= f.hidden_field :user_id, value: @user.id %>
+          <div class="mb-4 max-w-2xl">
+            <div class="mb-3">
+              <%= label_tag :push_title, 'Title', class: 'block text-xs font-medium text-slate-600 mb-1' %>
+              <%= text_field_tag :push_title,
+                                  params[:push_title].presence || Notification::PushTestService.default_title,
+                                  class: 'border border-slate-100 p-1.5 rounded-md w-full text-sm' %>
+            </div>
+            <div>
+              <%= label_tag :push_body, 'Body', class: 'block text-xs font-medium text-slate-600 mb-1' %>
+              <%= text_area_tag :push_body,
+                                 params[:push_body].presence || Notification::PushTestService.default_body,
+                                 rows: 2,
+                                 class: 'border border-slate-100 p-1.5 rounded-md w-full text-sm' %>
+            </div>
+            <p class="text-xs text-slate-400 mt-1">Customers will see this text as a real push notification on their device.</p>
+          </div>
+          <table class="w-full text-sm border border-slate-100 rounded-md">
+            <thead class="text-left text-xs text-slate-500 bg-slate-25">
+              <tr>
+                <th class="px-3 py-2 align-middle first:!pl-4 last:!pr-4"><input type="checkbox" id="toggle-all"></th>
+                <th class="px-3 py-2 first:!pl-4 last:!pr-4">ID</th>
+                <th class="px-3 py-2 first:!pl-4 last:!pr-4">Type</th>
+                <th class="px-3 py-2 first:!pl-4 last:!pr-4">Device / endpoint</th>
+                <th class="px-3 py-2 first:!pl-4 last:!pr-4">Push token</th>
+                <th class="px-3 py-2 first:!pl-4 last:!pr-4">Device details</th>
+                <th class="px-3 py-2 first:!pl-4 last:!pr-4">Created</th>
+                <th class="px-3 py-2 first:!pl-4 last:!pr-4">Last updated</th>
+              </tr>
+            </thead>
+            <tbody>
+              <% @subscriptions.each do |sub| %>
+                <% attrs = (sub.subscription_attributes || {}).stringify_keys %>
+                <% if sub.browser_push? %>
+                  <% endpoint = attrs['endpoint'].to_s %>
+                  <% host = (begin; URI.parse(endpoint).host; rescue URI::InvalidURIError; nil; end) %>
+                  <% device_display = host.presence || endpoint.presence || '—' %>
+                  <% token_display = endpoint.present? ? "…#{endpoint.last(6)}" : '—' %>
+                <% else %>
+                  <% device_display = attrs['device_id'].present? ? "…#{attrs['device_id'].to_s.last(6)}" : '—' %>
+                  <% token_display = attrs['push_token'].present? ? "…#{attrs['push_token'].to_s.last(6)}" : '—' %>
+                <% end %>
+                <% extra_attrs = attrs.except('endpoint', 'p256dh', 'auth', 'push_token', 'device_id') %>
+                <tr class="border-t border-slate-100 align-middle">
+                  <td class="px-3 py-2 first:!pl-4 last:!pr-4">
+                    <%= check_box_tag 'subscription_ids[]', sub.id, false, class: 'subscription-checkbox' %>
+                  </td>
+                  <td class="px-3 py-2 first:!pl-4 last:!pr-4"><%= sub.id %></td>
+                  <td class="px-3 py-2 first:!pl-4 last:!pr-4"><%= sub.subscription_type %></td>
+                  <td class="px-3 py-2 first:!pl-4 last:!pr-4 font-mono text-xs break-all"><%= device_display %></td>
+                  <td class="px-3 py-2 first:!pl-4 last:!pr-4 font-mono text-xs break-all"><%= token_display %></td>
+                  <td class="px-3 py-2 first:!pl-4 last:!pr-4 text-xs align-top">
+                    <% if extra_attrs.present? %>
+                      <% extra_attrs.each do |k, v| %>
+                        <div><span class="text-slate-500"><%= k %>:</span> <span class="font-mono"><%= v.to_s.truncate(40) %></span></div>
+                      <% end %>
+                    <% else %>
+                      <span class="text-slate-400">—</span>
+                    <% end %>
+                  </td>
+                  <td class="px-3 py-2 first:!pl-4 last:!pr-4 whitespace-nowrap"><%= sub.created_at.strftime('%Y-%m-%d %H:%M') %></td>
+                  <td class="px-3 py-2 first:!pl-4 last:!pr-4 whitespace-nowrap">
+                    <%= sub.updated_at.strftime('%Y-%m-%d %H:%M') %>
+                    <span class="text-xs text-slate-400">(<%= time_ago_in_words(sub.updated_at) %> ago)</span>
+                  </td>
+                </tr>
+              <% end %>
+            </tbody>
+          </table>
+          <div class="mt-4 flex gap-2">
+            <%= f.submit 'Send Test Push to Selected',
+                         class: 'border border-slate-200 bg-slate-50 px-3 py-1.5 rounded-md cursor-pointer font-medium' %>
+            <%= submit_tag 'Delete Selected Subscriptions',
+                           formaction: destroy_subscriptions_super_admin_push_diagnostics_path,
+                           formmethod: 'post',
+                           data: { confirm: "Delete the selected subscription(s)? The user won't receive pushes on those devices until their app re-registers." },
+                           class: 'border border-red-200 bg-red-50 text-red-700 px-3 py-1.5 rounded-md cursor-pointer font-medium' %>
+          </div>
+        <% end %>
+      <% end %>
+    </div>
+
+    <% if @results.present? %>
+      <div class="mb-8">
+        <h2 class="text-base font-semibold mb-2">3. Results</h2>
+        <table class="w-full text-sm border border-slate-100 rounded-md">
+          <thead class="text-left text-xs text-slate-500 bg-slate-25">
+            <tr>
+              <th class="px-3 py-2 first:!pl-4 last:!pr-4">Sub ID</th>
+              <th class="px-3 py-2 first:!pl-4 last:!pr-4">Type</th>
+              <th class="px-3 py-2 first:!pl-4 last:!pr-4">Device</th>
+              <th class="px-3 py-2 first:!pl-4 last:!pr-4">Push token</th>
+              <th class="px-3 py-2 first:!pl-4 last:!pr-4">Status</th>
+              <th class="px-3 py-2 first:!pl-4 last:!pr-4">Details</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @results.each do |r| %>
+              <tr class="border-t border-slate-100 align-top">
+                <td class="px-3 py-2 first:!pl-4 last:!pr-4"><%= r[:id] %></td>
+                <td class="px-3 py-2 first:!pl-4 last:!pr-4"><%= r[:type] %></td>
+                <td class="px-3 py-2 first:!pl-4 last:!pr-4 font-mono text-xs break-all"><%= r[:device] %></td>
+                <td class="px-3 py-2 first:!pl-4 last:!pr-4 font-mono text-xs break-all"><%= r[:token_tail] %></td>
+                <td class="px-3 py-2 first:!pl-4 last:!pr-4">
+                  <%
+                    color = {
+                      success: 'bg-green-100 text-green-800',
+                      failure: 'bg-red-100 text-red-800',
+                      skipped: 'bg-slate-100 text-slate-600'
+                    }[r[:status]]
+                  %>
+                  <span class="px-2 py-0.5 rounded-full text-xs <%= color %>"><%= r[:status] %></span>
+                </td>
+                <td class="px-3 py-2 first:!pl-4 last:!pr-4 font-mono text-xs break-all whitespace-pre-wrap"><%= r[:message] %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    <% end %>
+  <% end %>
+</section>
+
+<% content_for :javascript do %>
+  <script>
+    document.addEventListener('DOMContentLoaded', () => {
+      const toggle = document.getElementById('toggle-all');
+      if (!toggle) return;
+      toggle.addEventListener('change', (event) => {
+        document.querySelectorAll('.subscription-checkbox').forEach((cb) => {
+          cb.checked = event.target.checked;
+        });
+      });
+    });
+  </script>
+<% end %>
diff --git a/config/locales/en.yml b/config/locales/en.yml
index 057f41b81..1841db332 100644
--- a/config/locales/en.yml
+++ b/config/locales/en.yml
@@ -496,3 +496,9 @@ en:
       subject: 'Finish setting up %{custom_domain}'
     ssl_status:
       custom_domain_not_configured: 'Custom domain is not configured'
+  super_admin:
+    push_diagnostics:
+      user_not_found: 'User not found.'
+      no_subscriptions_to_test: 'Select at least one subscription to test.'
+      no_subscriptions_to_delete: 'Select at least one subscription to delete.'
+      subscriptions_deleted: "Deleted %{count} subscription(s). The user's device(s) will re-register on next app launch."
diff --git a/config/routes.rb b/config/routes.rb
index 31453b157..2461539ad 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -625,6 +625,9 @@ Rails.application.routes.draw do
       root to: 'dashboard#index'
 
       resource :app_config, only: [:show, :create]
+      resource :push_diagnostics, only: [:show, :create] do
+        post :destroy_subscriptions, on: :collection
+      end
 
       # order of resources affect the order of sidebar navigation in super admin
       resources :accounts, only: [:index, :new, :create, :show, :edit, :update, :destroy] do
diff --git a/lib/chatwoot_hub.rb b/lib/chatwoot_hub.rb
index be5a07e05..95679ed73 100644
--- a/lib/chatwoot_hub.rb
+++ b/lib/chatwoot_hub.rb
@@ -106,14 +106,18 @@ class ChatwootHub
   end
 
   def self.send_push(fcm_options)
-    info = { fcm_options: fcm_options }
-    RestClient.post(push_notification_url, info.merge(instance_config).to_json, { content_type: :json, accept: :json })
+    send_push_with_response(fcm_options)
   rescue *ExceptionList::REST_CLIENT_EXCEPTIONS => e
     Rails.logger.error "Exception: #{e.message}"
   rescue StandardError => e
     ChatwootExceptionTracker.new(e).capture_exception
   end
 
+  def self.send_push_with_response(fcm_options)
+    info = { fcm_options: fcm_options }
+    RestClient.post(push_notification_url, info.merge(instance_config).to_json, { content_type: :json, accept: :json })
+  end
+
   def self.emit_event(event_name, event_data)
     return if ENV['DISABLE_TELEMETRY']
 

From ca66218cb9f94869138d1b23fb00e5bf8c079d40 Mon Sep 17 00:00:00 2001
From: Muhsin Keloth <muhsinkeramam@gmail.com>
Date: Tue, 21 Apr 2026 19:16:08 +0400
Subject: [PATCH 3/7] Revert: Validate Twilio webhook signatures
 (X-Twilio-Signature) (#14125)

Reverts chatwoot/chatwoot#13638
---
 .../twilio_signature_verify_concern.rb        |  88 -----------
 app/controllers/twilio/callback_controller.rb |   2 -
 .../twilio/delivery_status_controller.rb      |   6 -
 .../twilio/callbacks_controller_spec.rb       | 149 +-----------------
 .../twilio/delivery_status_controller_spec.rb | 123 +--------------
 5 files changed, 14 insertions(+), 354 deletions(-)
 delete mode 100644 app/controllers/concerns/twilio_signature_verify_concern.rb

diff --git a/app/controllers/concerns/twilio_signature_verify_concern.rb b/app/controllers/concerns/twilio_signature_verify_concern.rb
deleted file mode 100644
index b7a4754a4..000000000
--- a/app/controllers/concerns/twilio_signature_verify_concern.rb
+++ /dev/null
@@ -1,88 +0,0 @@
-module TwilioSignatureVerifyConcern
-  extend ActiveSupport::Concern
-
-  included do
-    before_action :verify_twilio_signature!
-  end
-
-  private
-
-  def verify_twilio_signature!
-    channel = find_twilio_channel
-    return log_and_reject_missing_channel if channel.blank?
-    return if channel.api_key_sid.present? && log_api_key_skip(channel)
-
-    head :forbidden unless valid_signature?(channel)
-  end
-
-  def log_and_reject_missing_channel
-    Rails.logger.warn(
-      '[TWILIO] Channel not found for webhook ' \
-      "account_sid=#{params[:AccountSid]} messaging_service_sid=#{params[:MessagingServiceSid]} " \
-      "to=#{params[:To]} from=#{params[:From]}"
-    )
-    head :forbidden
-  end
-
-  def log_api_key_skip(channel)
-    Rails.logger.warn(
-      '[TWILIO] Signature validation skipped: channel uses API key authentication. ' \
-      "account_sid=#{params[:AccountSid]} channel_id=#{channel.id}"
-    )
-  end
-
-  def valid_signature?(channel)
-    signature = request.headers['X-Twilio-Signature']
-    if signature.blank?
-      Rails.logger.warn("[TWILIO] Missing X-Twilio-Signature header account_sid=#{params[:AccountSid]}")
-      return false
-    end
-
-    validator = Twilio::Security::RequestValidator.new(channel.auth_token)
-    request_url = reconstruct_url
-    return true if validator.validate(request_url, request.request_parameters, signature)
-
-    Rails.logger.warn(
-      '[TWILIO] Signature validation failed ' \
-      "account_sid=#{params[:AccountSid]} channel_id=#{channel.id} url=#{request_url} ip=#{request.remote_ip}"
-    )
-    false
-  end
-
-  def find_twilio_channel
-    if params[:MessagingServiceSid].present?
-      channel = ::Channel::TwilioSms.find_by(messaging_service_sid: params[:MessagingServiceSid])
-      return channel if channel.present? && (params[:AccountSid].blank? || channel.account_sid == params[:AccountSid])
-
-      return nil
-    end
-    return if params[:AccountSid].blank?
-
-    find_channel_by_phone_number
-  end
-
-  def find_channel_by_phone_number
-    channel_lookup_phone_numbers.each do |phone|
-      channel = ::Channel::TwilioSms.find_by(account_sid: params[:AccountSid], phone_number: phone)
-      return channel if channel
-    end
-    nil
-  end
-
-  def channel_lookup_phone_numbers
-    [params[:To], params[:From]].compact_blank
-  end
-
-  def reconstruct_url
-    url = request.original_url
-    url = url.sub('http://', 'https://') if url.start_with?('http://') && https_request?
-    url
-  end
-
-  def https_request?
-    return true if request.ssl?
-
-    forwarded_proto = request.headers['X-Forwarded-Proto'].to_s.split(',').map(&:strip).find(&:present?)
-    forwarded_proto&.casecmp?('https')
-  end
-end
diff --git a/app/controllers/twilio/callback_controller.rb b/app/controllers/twilio/callback_controller.rb
index 9b42cd034..d607ba151 100644
--- a/app/controllers/twilio/callback_controller.rb
+++ b/app/controllers/twilio/callback_controller.rb
@@ -1,6 +1,4 @@
 class Twilio::CallbackController < ApplicationController
-  include TwilioSignatureVerifyConcern
-
   def create
     Webhooks::TwilioEventsJob.perform_later(permitted_params.to_unsafe_hash)
 
diff --git a/app/controllers/twilio/delivery_status_controller.rb b/app/controllers/twilio/delivery_status_controller.rb
index 8e846a737..1c756a1c2 100644
--- a/app/controllers/twilio/delivery_status_controller.rb
+++ b/app/controllers/twilio/delivery_status_controller.rb
@@ -1,6 +1,4 @@
 class Twilio::DeliveryStatusController < ApplicationController
-  include TwilioSignatureVerifyConcern
-
   def create
     Webhooks::TwilioDeliveryStatusJob.perform_later(permitted_params.to_unsafe_hash)
 
@@ -20,8 +18,4 @@ class Twilio::DeliveryStatusController < ApplicationController
       :ErrorMessage
     )
   end
-
-  def channel_lookup_phone_numbers
-    [params[:From]].compact_blank
-  end
 end
diff --git a/spec/controllers/twilio/callbacks_controller_spec.rb b/spec/controllers/twilio/callbacks_controller_spec.rb
index 09b558096..d16acf229 100644
--- a/spec/controllers/twilio/callbacks_controller_spec.rb
+++ b/spec/controllers/twilio/callbacks_controller_spec.rb
@@ -4,160 +4,25 @@ RSpec.describe 'Twilio::CallbacksController', type: :request do
   include Rails.application.routes.url_helpers
 
   describe 'POST /twilio/callback' do
-    let(:account) { create(:account) }
-    let(:twilio_channel) { create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123') }
     let(:params) do
       {
         'From' => '+1234567890',
-        'To' => twilio_channel.phone_number,
+        'To' => '+0987654321',
         'Body' => 'Test message',
         'AccountSid' => 'AC123',
         'SmsSid' => 'SM123'
       }
     end
 
-    def post_with_signature(url, params:)
-      validator = Twilio::Security::RequestValidator.new(twilio_channel.auth_token)
-      signature = validator.build_signature_for(url, params)
-      post url, params: params, headers: { 'X-Twilio-Signature' => signature }
-    end
-
-    context 'with valid signature' do
-      it 'enqueues the Twilio events job' do
-        url = twilio_callback_index_url
-        expect do
-          post_with_signature(url, params: params)
-        end.to have_enqueued_job(Webhooks::TwilioEventsJob)
-      end
-
-      it 'returns no content status' do
-        url = twilio_callback_index_url
-        post_with_signature(url, params: params)
-        expect(response).to have_http_status(:no_content)
-      end
-    end
-
-    context 'with invalid signature' do
-      it 'returns forbidden status' do
-        post twilio_callback_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
-        expect(response).to have_http_status(:forbidden)
-      end
-
-      it 'does not enqueue the job' do
-        expect do
-          post twilio_callback_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
-        end.not_to have_enqueued_job(Webhooks::TwilioEventsJob)
-      end
-    end
-
-    context 'with missing signature header' do
-      it 'returns forbidden status' do
+    it 'enqueues the Twilio events job' do
+      expect do
         post twilio_callback_index_url, params: params
-        expect(response).to have_http_status(:forbidden)
-      end
+      end.to have_enqueued_job(Webhooks::TwilioEventsJob).with(params)
     end
 
-    context 'when channel is not found' do
-      it 'returns forbidden status' do
-        post twilio_callback_index_url, params: params.merge('AccountSid' => 'UNKNOWN', 'To' => '+0000000000')
-        expect(response).to have_http_status(:forbidden)
-      end
-    end
-
-    context 'when channel uses API key authentication' do
-      let(:twilio_channel) do
-        create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123', api_key_sid: 'SK123')
-      end
-
-      it 'skips signature validation and enqueues the job' do
-        expect do
-          post twilio_callback_index_url, params: params
-        end.to have_enqueued_job(Webhooks::TwilioEventsJob)
-      end
-    end
-
-    context 'when behind a reverse proxy with X-Forwarded-Proto' do
-      it 'validates signature against the HTTPS URL' do
-        http_url = twilio_callback_index_url
-        https_url = http_url.sub('http://', 'https://')
-        validator = Twilio::Security::RequestValidator.new(twilio_channel.auth_token)
-        signature = validator.build_signature_for(https_url, params)
-        post http_url, params: params, headers: {
-          'X-Twilio-Signature' => signature,
-          'X-Forwarded-Proto' => 'https'
-        }
-        expect(response).to have_http_status(:no_content)
-      end
-
-      it 'validates signature when forwarded proto is a comma-separated chain' do
-        http_url = twilio_callback_index_url
-        https_url = http_url.sub('http://', 'https://')
-        validator = Twilio::Security::RequestValidator.new(twilio_channel.auth_token)
-        signature = validator.build_signature_for(https_url, params)
-        post http_url, params: params, headers: {
-          'X-Twilio-Signature' => signature,
-          'X-Forwarded-Proto' => 'https,http'
-        }
-        expect(response).to have_http_status(:no_content)
-      end
-    end
-
-    context 'with MessagingServiceSid lookup' do
-      let(:twilio_channel) { create(:channel_twilio_sms, account: account, account_sid: 'AC123') }
-      let(:params) do
-        {
-          'From' => '+1234567890',
-          'Body' => 'Test message',
-          'AccountSid' => 'AC123',
-          'SmsSid' => 'SM123',
-          'MessagingServiceSid' => twilio_channel.messaging_service_sid
-        }
-      end
-
-      it 'validates and enqueues the job' do
-        url = twilio_callback_index_url
-        post_with_signature(url, params: params)
-        expect(response).to have_http_status(:no_content)
-      end
-    end
-
-    context 'when MessagingServiceSid is present but does not match a channel' do
-      let(:params) do
-        {
-          'From' => '+1234567890',
-          'To' => twilio_channel.phone_number,
-          'Body' => 'Test message',
-          'AccountSid' => 'AC123',
-          'SmsSid' => 'SM123',
-          'MessagingServiceSid' => 'MG_UNKNOWN'
-        }
-      end
-
-      it 'returns forbidden without falling back to phone number lookup' do
-        url = twilio_callback_index_url
-        post_with_signature(url, params: params)
-        expect(response).to have_http_status(:forbidden)
-      end
-    end
-
-    context 'when MessagingServiceSid matches a channel but AccountSid does not' do
-      let(:other_channel) { create(:channel_twilio_sms, account: account, account_sid: 'AC_OTHER') }
-      let(:params) do
-        {
-          'From' => '+1234567890',
-          'To' => twilio_channel.phone_number,
-          'Body' => 'Test message',
-          'AccountSid' => 'AC123',
-          'SmsSid' => 'SM123',
-          'MessagingServiceSid' => other_channel.messaging_service_sid
-        }
-      end
-
-      it 'returns forbidden without falling back to phone number lookup' do
-        url = twilio_callback_index_url
-        post_with_signature(url, params: params)
-        expect(response).to have_http_status(:forbidden)
-      end
+    it 'returns no content status' do
+      post twilio_callback_index_url, params: params
+      expect(response).to have_http_status(:no_content)
     end
   end
 end
diff --git a/spec/controllers/twilio/delivery_status_controller_spec.rb b/spec/controllers/twilio/delivery_status_controller_spec.rb
index dc99fdf23..fc21f8f94 100644
--- a/spec/controllers/twilio/delivery_status_controller_spec.rb
+++ b/spec/controllers/twilio/delivery_status_controller_spec.rb
@@ -4,132 +4,23 @@ RSpec.describe 'Twilio::DeliveryStatusController', type: :request do
   include Rails.application.routes.url_helpers
 
   describe 'POST /twilio/delivery_status' do
-    let(:account) { create(:account) }
-    let(:twilio_channel) { create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123') }
     let(:params) do
       {
         'MessageSid' => 'SM123',
         'MessageStatus' => 'delivered',
-        'AccountSid' => 'AC123',
-        'From' => twilio_channel.phone_number
+        'AccountSid' => 'AC123'
       }
     end
 
-    def post_with_signature(url, params:, channel: twilio_channel)
-      validator = Twilio::Security::RequestValidator.new(channel.auth_token)
-      signature = validator.build_signature_for(url, params)
-      post url, params: params, headers: { 'X-Twilio-Signature' => signature }
-    end
-
-    context 'with valid signature' do
-      it 'enqueues the delivery status job' do
-        url = twilio_delivery_status_index_url
-        expect do
-          post_with_signature(url, params: params)
-        end.to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
-      end
-
-      it 'returns no content status' do
-        url = twilio_delivery_status_index_url
-        post_with_signature(url, params: params)
-        expect(response).to have_http_status(:no_content)
-      end
-    end
-
-    context 'with invalid signature' do
-      it 'returns forbidden status' do
-        post twilio_delivery_status_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
-        expect(response).to have_http_status(:forbidden)
-      end
-
-      it 'does not enqueue the job' do
-        expect do
-          post twilio_delivery_status_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
-        end.not_to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
-      end
-    end
-
-    context 'with missing signature header' do
-      it 'returns forbidden status' do
+    it 'enqueues the Twilio delivery status job' do
+      expect do
         post twilio_delivery_status_index_url, params: params
-        expect(response).to have_http_status(:forbidden)
-      end
+      end.to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob).with(params)
     end
 
-    context 'when channel uses API key authentication' do
-      let(:twilio_channel) do
-        create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123', api_key_sid: 'SK123')
-      end
-
-      it 'skips signature validation and enqueues the job' do
-        expect do
-          post twilio_delivery_status_index_url, params: params
-        end.to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
-      end
-    end
-
-    context 'with MessagingServiceSid lookup' do
-      let(:twilio_channel) { create(:channel_twilio_sms, account: account, account_sid: 'AC123') }
-      let(:params) do
-        {
-          'MessageSid' => 'SM123',
-          'MessageStatus' => 'delivered',
-          'AccountSid' => 'AC123',
-          'MessagingServiceSid' => twilio_channel.messaging_service_sid
-        }
-      end
-
-      it 'validates and enqueues the job' do
-        url = twilio_delivery_status_index_url
-        post_with_signature(url, params: params)
-        expect(response).to have_http_status(:no_content)
-      end
-    end
-
-    context 'when To does not map to a channel but From does' do
-      let(:params) do
-        {
-          'MessageSid' => 'SM123',
-          'MessageStatus' => 'delivered',
-          'AccountSid' => 'AC123',
-          'To' => '+19999999999',
-          'From' => twilio_channel.phone_number
-        }
-      end
-
-      it 'falls back to From lookup and enqueues the delivery status job' do
-        url = twilio_delivery_status_index_url
-
-        expect do
-          post_with_signature(url, params: params)
-        end.to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
-
-        expect(response).to have_http_status(:no_content)
-      end
-    end
-
-    context 'when To maps to an API-key channel but From maps to a different channel' do
-      let!(:api_key_channel) do
-        create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123', api_key_sid: 'SK123')
-      end
-      let!(:from_channel) { create(:channel_twilio_sms, :with_phone_number, account: account, account_sid: 'AC123') }
-      let(:params) do
-        {
-          'MessageSid' => 'SM123',
-          'MessageStatus' => 'delivered',
-          'AccountSid' => 'AC123',
-          'To' => api_key_channel.phone_number,
-          'From' => from_channel.phone_number
-        }
-      end
-
-      it 'rejects invalid signatures instead of skipping verification' do
-        expect do
-          post twilio_delivery_status_index_url, params: params, headers: { 'X-Twilio-Signature' => 'invalid' }
-        end.not_to have_enqueued_job(Webhooks::TwilioDeliveryStatusJob)
-
-        expect(response).to have_http_status(:forbidden)
-      end
+    it 'returns no content status' do
+      post twilio_delivery_status_index_url, params: params
+      expect(response).to have_http_status(:no_content)
     end
   end
 end

From f12118a3c07d8de30a710357b84f18dddacbed0b Mon Sep 17 00:00:00 2001
From: Tanmay Deep Sharma <32020192+tds-1@users.noreply.github.com>
Date: Wed, 22 Apr 2026 11:21:26 +0700
Subject: [PATCH 4/7] fix: void topup invoice when card payment fails (#14104)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a credit top-up's card charge fails, the finalized invoice was left
in an open state with no hook back into our fulfillment service. If that
invoice was later paid (manually via the hosted invoice page, or by a
future dunning flow), the account would never receive its credits —
silent revenue loss.

This change voids the invoice the moment the charge fails, so a failed
top-up cannot turn into a paid-but-unfulfilled invoice.

## Closes

<!-- add the relevant issue / Linear link -->

## How to test

1. On a Business-plan account with a Stripe customer, attach a test card
that will decline on charge (e.g. `4000 0000 0000 0002`).
2. From the dashboard, open the credit top-up flow and purchase a credit
pack.
3. Observe the API returns an error and the account's captain credits
are unchanged.
4. In the Stripe dashboard, confirm the corresponding invoice is in
`void` status (not `open`).
5. Repeat with a good card (`4242 4242 4242 4242`) and confirm the happy
path still fulfills credits.

## What changed

- `finalize_and_pay` in `Enterprise::Billing::TopupCheckoutService` now
rescues `Stripe::CardError`, voids the open invoice via
`Stripe::Invoice.void_invoice`, and re-raises so the controller surfaces
the original decline error to the client.
- Rescue is intentionally narrow to `Stripe::CardError` (declines,
insufficient funds, SCA `authentication_required`). Transient errors
like `APIConnectionError` / `RateLimitError` are left to propagate — the
charge may have actually succeeded and voiding could be wrong.
- Invoices are created with `auto_advance: false`, so Stripe's Smart
Retries won't collect on an open invoice; voiding is the correct
terminal state.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../services/enterprise/billing/topup_checkout_service.rb  | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/enterprise/app/services/enterprise/billing/topup_checkout_service.rb b/enterprise/app/services/enterprise/billing/topup_checkout_service.rb
index d0ec3e372..00e2b1646 100644
--- a/enterprise/app/services/enterprise/billing/topup_checkout_service.rb
+++ b/enterprise/app/services/enterprise/billing/topup_checkout_service.rb
@@ -79,7 +79,12 @@ class Enterprise::Billing::TopupCheckoutService
   def finalize_and_pay(invoice_id)
     Stripe::Invoice.finalize_invoice(invoice_id, { auto_advance: false })
     invoice = Stripe::Invoice.retrieve(invoice_id)
-    Stripe::Invoice.pay(invoice_id) unless invoice.status == 'paid'
+    return if invoice.status == 'paid'
+
+    Stripe::Invoice.pay(invoice_id)
+  rescue Stripe::CardError
+    Stripe::Invoice.void_invoice(invoice_id)
+    raise
   end
 
   def fulfill_credits(credits, topup_option)

From 475db8531817ab23e56a8d1e38cad38d60f15fee Mon Sep 17 00:00:00 2001
From: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>
Date: Wed, 22 Apr 2026 17:13:26 +0530
Subject: [PATCH 5/7] fix: prevent template picker dropdown cut-off in compose
 form (#14129)

---
 .../NewConversation/ComposeConversation.vue   |   1 +
 .../components/ActionButtons.vue              |   2 +-
 .../components/ContentTemplateForm.vue        |   4 +-
 .../components/ContentTemplateSelector.vue    | 120 ++++++++++--------
 .../components/WhatsAppOptions.vue            | 111 ++++++++--------
 .../components/WhatsappTemplate.vue           |   4 +-
 .../components-next/popover/Popover.vue       |  28 +++-
 .../modules/contact/ContactDeleteModal.vue    |   4 +-
 .../modules/contact/ContactMergeModal.vue     |   4 +-
 9 files changed, 154 insertions(+), 124 deletions(-)

diff --git a/app/javascript/dashboard/components-next/NewConversation/ComposeConversation.vue b/app/javascript/dashboard/components-next/NewConversation/ComposeConversation.vue
index 1ab370901..02a00c703 100644
--- a/app/javascript/dashboard/components-next/NewConversation/ComposeConversation.vue
+++ b/app/javascript/dashboard/components-next/NewConversation/ComposeConversation.vue
@@ -233,6 +233,7 @@ onMounted(() => resetContacts());
   <Popover
     ref="popoverRef"
     :align="align"
+    :show-content-border="false"
     @show="onPopoverShow"
     @hide="onPopoverHide"
   >
diff --git a/app/javascript/dashboard/components-next/NewConversation/components/ActionButtons.vue b/app/javascript/dashboard/components-next/NewConversation/components/ActionButtons.vue
index aec05a717..e8f484997 100644
--- a/app/javascript/dashboard/components-next/NewConversation/components/ActionButtons.vue
+++ b/app/javascript/dashboard/components-next/NewConversation/components/ActionButtons.vue
@@ -20,6 +20,7 @@ const props = defineProps({
   isEmailOrWebWidgetInbox: { type: Boolean, default: false },
   isTwilioSmsInbox: { type: Boolean, default: false },
   isTwilioWhatsAppInbox: { type: Boolean, default: false },
+  // eslint-disable-next-line vue/no-unused-properties
   messageTemplates: { type: Array, default: () => [] },
   channelType: { type: String, default: '' },
   isLoading: { type: Boolean, default: false },
@@ -198,7 +199,6 @@ useEventListener(document, 'paste', onPaste);
       <WhatsAppOptions
         v-if="isWhatsappInbox"
         :inbox-id="inboxId"
-        :message-templates="messageTemplates"
         @send-message="emit('sendWhatsappMessage', $event)"
       />
       <ContentTemplateSelector
diff --git a/app/javascript/dashboard/components-next/NewConversation/components/ContentTemplateForm.vue b/app/javascript/dashboard/components-next/NewConversation/components/ContentTemplateForm.vue
index 18a219605..20f32e854 100644
--- a/app/javascript/dashboard/components-next/NewConversation/components/ContentTemplateForm.vue
+++ b/app/javascript/dashboard/components-next/NewConversation/components/ContentTemplateForm.vue
@@ -24,9 +24,7 @@ const handleBack = () => {
 </script>
 
 <template>
-  <div
-    class="absolute top-full mt-1.5 max-h-[30rem] overflow-y-auto ltr:left-0 rtl:right-0 flex flex-col gap-4 px-4 pt-6 pb-5 items-start w-[28.75rem] h-auto bg-n-solid-2 border border-n-strong shadow-sm rounded-lg"
-  >
+  <div class="flex flex-col gap-4 px-4 pt-6 pb-5 items-start w-[28.75rem]">
     <div class="w-full">
       <ContentTemplateParser
         :template="template"
diff --git a/app/javascript/dashboard/components-next/NewConversation/components/ContentTemplateSelector.vue b/app/javascript/dashboard/components-next/NewConversation/components/ContentTemplateSelector.vue
index 684429182..f2061c775 100644
--- a/app/javascript/dashboard/components-next/NewConversation/components/ContentTemplateSelector.vue
+++ b/app/javascript/dashboard/components-next/NewConversation/components/ContentTemplateSelector.vue
@@ -6,6 +6,7 @@ import { useMapGetter } from 'dashboard/composables/store';
 import Icon from 'dashboard/components-next/icon/Icon.vue';
 import Button from 'dashboard/components-next/button/Button.vue';
 import Input from 'dashboard/components-next/input/Input.vue';
+import Popover from 'dashboard/components-next/popover/Popover.vue';
 import ContentTemplateForm from './ContentTemplateForm.vue';
 
 const props = defineProps({
@@ -22,7 +23,6 @@ const inbox = useMapGetter('inboxes/getInbox');
 
 const searchQuery = ref('');
 const selectedTemplate = ref(null);
-const showTemplatesMenu = ref(false);
 
 const contentTemplates = computed(() => {
   const inboxData = inbox.value(props.inboxId);
@@ -39,29 +39,36 @@ const filteredTemplates = computed(() => {
   );
 });
 
-const handleTriggerClick = () => {
+const handlePopoverShow = () => {
   searchQuery.value = '';
-  showTemplatesMenu.value = !showTemplatesMenu.value;
+  selectedTemplate.value = null;
+};
+
+const handlePopoverHide = () => {
+  selectedTemplate.value = null;
 };
 
 const handleTemplateClick = template => {
   selectedTemplate.value = template;
-  showTemplatesMenu.value = false;
 };
 
 const handleBack = () => {
   selectedTemplate.value = null;
-  showTemplatesMenu.value = true;
 };
 
-const handleSendMessage = template => {
+const handleSendMessage = (template, hide) => {
   emit('sendMessage', template);
-  selectedTemplate.value = null;
+  hide();
 };
 </script>
 
 <template>
-  <div class="relative">
+  <Popover
+    align="start"
+    disable-mobile-view
+    @show="handlePopoverShow"
+    @hide="handlePopoverHide"
+  >
     <Button
       icon="i-ph-whatsapp-logo"
       :label="t('COMPOSE_NEW_CONVERSATION.FORM.TWILIO_OPTIONS.LABEL')"
@@ -69,56 +76,59 @@ const handleSendMessage = template => {
       size="sm"
       :disabled="selectedTemplate"
       class="!text-xs font-medium"
-      @click="handleTriggerClick"
     />
-    <div
-      v-if="showTemplatesMenu"
-      class="absolute top-full mt-1.5 max-h-96 overflow-y-auto ltr:left-0 rtl:right-0 flex flex-col gap-2 p-4 items-center w-[21.875rem] h-auto bg-n-solid-2 border border-n-strong shadow-sm rounded-lg"
-    >
-      <div class="w-full">
-        <Input
-          v-model="searchQuery"
-          type="search"
-          :placeholder="
-            t('COMPOSE_NEW_CONVERSATION.FORM.TWILIO_OPTIONS.SEARCH_PLACEHOLDER')
-          "
-          custom-input-class="ltr:pl-10 rtl:pr-10"
-        >
-          <template #prefix>
-            <Icon
-              icon="i-lucide-search"
-              class="absolute top-2 size-3.5 ltr:left-3 rtl:right-3"
-            />
-          </template>
-        </Input>
-      </div>
+    <template #content="{ hide }">
       <div
-        v-for="template in filteredTemplates"
-        :key="template.content_sid"
-        tabindex="0"
-        class="flex flex-col gap-2 p-2 w-full rounded-lg cursor-pointer dark:hover:bg-n-alpha-3 hover:bg-n-alpha-1"
-        @click="handleTemplateClick(template)"
+        v-if="!selectedTemplate"
+        class="flex flex-col gap-2 p-4 items-center w-[21.875rem]"
       >
-        <div class="flex justify-between items-center">
-          <span class="text-sm text-n-slate-12">{{
-            template.friendly_name
-          }}</span>
+        <div class="w-full">
+          <Input
+            v-model="searchQuery"
+            type="search"
+            :placeholder="
+              t(
+                'COMPOSE_NEW_CONVERSATION.FORM.TWILIO_OPTIONS.SEARCH_PLACEHOLDER'
+              )
+            "
+            custom-input-class="ltr:pl-10 rtl:pr-10"
+          >
+            <template #prefix>
+              <Icon
+                icon="i-lucide-search"
+                class="absolute top-2 size-3.5 ltr:left-3 rtl:right-3"
+              />
+            </template>
+          </Input>
         </div>
-        <p class="mb-0 text-xs leading-5 text-n-slate-11 line-clamp-2">
-          {{ template.body || t('CONTENT_TEMPLATES.PICKER.NO_CONTENT') }}
-        </p>
+        <div
+          v-for="template in filteredTemplates"
+          :key="template.content_sid"
+          tabindex="0"
+          class="flex flex-col gap-2 p-2 w-full rounded-lg cursor-pointer dark:hover:bg-n-alpha-3 hover:bg-n-alpha-1"
+          @click="handleTemplateClick(template)"
+        >
+          <div class="flex justify-between items-center">
+            <span class="text-sm text-n-slate-12">{{
+              template.friendly_name
+            }}</span>
+          </div>
+          <p class="mb-0 text-xs leading-5 text-n-slate-11 line-clamp-2">
+            {{ template.body || t('CONTENT_TEMPLATES.PICKER.NO_CONTENT') }}
+          </p>
+        </div>
+        <template v-if="filteredTemplates.length === 0">
+          <p class="pt-2 w-full text-sm text-n-slate-11">
+            {{ t('COMPOSE_NEW_CONVERSATION.FORM.TWILIO_OPTIONS.EMPTY_STATE') }}
+          </p>
+        </template>
       </div>
-      <template v-if="filteredTemplates.length === 0">
-        <p class="pt-2 w-full text-sm text-n-slate-11">
-          {{ t('COMPOSE_NEW_CONVERSATION.FORM.TWILIO_OPTIONS.EMPTY_STATE') }}
-        </p>
-      </template>
-    </div>
-    <ContentTemplateForm
-      v-if="selectedTemplate"
-      :template="selectedTemplate"
-      @send-message="handleSendMessage"
-      @back="handleBack"
-    />
-  </div>
+      <ContentTemplateForm
+        v-else
+        :template="selectedTemplate"
+        @send-message="payload => handleSendMessage(payload, hide)"
+        @back="handleBack"
+      />
+    </template>
+  </Popover>
 </template>
diff --git a/app/javascript/dashboard/components-next/NewConversation/components/WhatsAppOptions.vue b/app/javascript/dashboard/components-next/NewConversation/components/WhatsAppOptions.vue
index e5350c1fb..10068ec3d 100644
--- a/app/javascript/dashboard/components-next/NewConversation/components/WhatsAppOptions.vue
+++ b/app/javascript/dashboard/components-next/NewConversation/components/WhatsAppOptions.vue
@@ -5,6 +5,7 @@ import { useMapGetter } from 'dashboard/composables/store';
 
 import Icon from 'dashboard/components-next/icon/Icon.vue';
 import Button from 'dashboard/components-next/button/Button.vue';
+import Popover from 'dashboard/components-next/popover/Popover.vue';
 import WhatsappTemplate from './WhatsappTemplate.vue';
 
 const props = defineProps({
@@ -24,8 +25,6 @@ const getFilteredWhatsAppTemplates = useMapGetter(
 const searchQuery = ref('');
 const selectedTemplate = ref(null);
 
-const showTemplatesMenu = ref(false);
-
 const whatsAppTemplateMessages = computed(() => {
   return getFilteredWhatsAppTemplates.value(props.inboxId);
 });
@@ -40,29 +39,36 @@ const getTemplateBody = template => {
   return template.components.find(component => component.type === 'BODY').text;
 };
 
-const handleTriggerClick = () => {
+const handlePopoverShow = () => {
   searchQuery.value = '';
-  showTemplatesMenu.value = !showTemplatesMenu.value;
+  selectedTemplate.value = null;
+};
+
+const handlePopoverHide = () => {
+  selectedTemplate.value = null;
 };
 
 const handleTemplateClick = template => {
   selectedTemplate.value = template;
-  showTemplatesMenu.value = false;
 };
 
 const handleBack = () => {
   selectedTemplate.value = null;
-  showTemplatesMenu.value = true;
 };
 
-const handleSendMessage = template => {
+const handleSendMessage = (template, hide) => {
   emit('sendMessage', template);
-  selectedTemplate.value = null;
+  hide();
 };
 </script>
 
 <template>
-  <div class="relative">
+  <Popover
+    align="start"
+    disable-mobile-view
+    @show="handlePopoverShow"
+    @hide="handlePopoverHide"
+  >
     <Button
       icon="i-ri-whatsapp-line"
       :label="t('COMPOSE_NEW_CONVERSATION.FORM.WHATSAPP_OPTIONS.LABEL')"
@@ -70,50 +76,53 @@ const handleSendMessage = template => {
       size="sm"
       :disabled="selectedTemplate"
       class="!text-xs font-medium"
-      @click="handleTriggerClick"
     />
-    <div
-      v-if="showTemplatesMenu"
-      class="absolute top-full mt-1.5 max-h-96 overflow-y-auto ltr:left-0 rtl:right-0 flex flex-col gap-2 p-4 items-center w-[21.875rem] h-auto bg-n-solid-2 border border-n-strong shadow-sm rounded-lg"
-    >
-      <div class="relative w-full">
-        <Icon
-          icon="i-lucide-search"
-          class="absolute size-3.5 top-2 ltr:left-3 rtl:right-3"
-        />
-        <input
-          v-model="searchQuery"
-          type="search"
-          :placeholder="
-            t(
-              'COMPOSE_NEW_CONVERSATION.FORM.WHATSAPP_OPTIONS.SEARCH_PLACEHOLDER'
-            )
-          "
-          class="w-full h-8 py-2 ltr:pl-10 rtl:pr-10 ltr:pr-2 rtl:pl-2 text-sm reset-base outline-none border-none rounded-lg bg-n-alpha-black2 dark:bg-n-solid-1 text-n-slate-12"
-        />
-      </div>
+    <template #content="{ hide }">
       <div
-        v-for="template in filteredTemplates"
-        :key="template.id"
-        class="flex flex-col gap-2 p-2 w-full rounded-lg cursor-pointer dark:hover:bg-n-alpha-3 hover:bg-n-alpha-1"
-        @click="handleTemplateClick(template)"
+        v-if="!selectedTemplate"
+        class="flex flex-col gap-2 p-4 items-center w-[21.875rem]"
       >
-        <span class="text-sm text-n-slate-12">{{ template.name }}</span>
-        <p class="mb-0 text-xs leading-5 text-n-slate-11 line-clamp-2">
-          {{ getTemplateBody(template) }}
-        </p>
+        <div class="relative w-full">
+          <Icon
+            icon="i-lucide-search"
+            class="absolute size-3.5 top-2 ltr:left-3 rtl:right-3"
+          />
+          <input
+            v-model="searchQuery"
+            type="search"
+            :placeholder="
+              t(
+                'COMPOSE_NEW_CONVERSATION.FORM.WHATSAPP_OPTIONS.SEARCH_PLACEHOLDER'
+              )
+            "
+            class="w-full h-8 py-2 ltr:pl-10 rtl:pr-10 ltr:pr-2 rtl:pl-2 text-sm reset-base outline-none border-none rounded-lg bg-n-alpha-black2 dark:bg-n-solid-1 text-n-slate-12"
+          />
+        </div>
+        <div
+          v-for="template in filteredTemplates"
+          :key="template.id"
+          class="flex flex-col gap-2 p-2 w-full rounded-lg cursor-pointer dark:hover:bg-n-alpha-3 hover:bg-n-alpha-1"
+          @click="handleTemplateClick(template)"
+        >
+          <span class="text-sm text-n-slate-12">{{ template.name }}</span>
+          <p class="mb-0 text-xs leading-5 text-n-slate-11 line-clamp-2">
+            {{ getTemplateBody(template) }}
+          </p>
+        </div>
+        <template v-if="filteredTemplates.length === 0">
+          <p class="pt-2 w-full text-sm text-n-slate-11">
+            {{
+              t('COMPOSE_NEW_CONVERSATION.FORM.WHATSAPP_OPTIONS.EMPTY_STATE')
+            }}
+          </p>
+        </template>
       </div>
-      <template v-if="filteredTemplates.length === 0">
-        <p class="pt-2 w-full text-sm text-n-slate-11">
-          {{ t('COMPOSE_NEW_CONVERSATION.FORM.WHATSAPP_OPTIONS.EMPTY_STATE') }}
-        </p>
-      </template>
-    </div>
-    <WhatsappTemplate
-      v-if="selectedTemplate"
-      :template="selectedTemplate"
-      @send-message="handleSendMessage"
-      @back="handleBack"
-    />
-  </div>
+      <WhatsappTemplate
+        v-else
+        :template="selectedTemplate"
+        @send-message="payload => handleSendMessage(payload, hide)"
+        @back="handleBack"
+      />
+    </template>
+  </Popover>
 </template>
diff --git a/app/javascript/dashboard/components-next/NewConversation/components/WhatsappTemplate.vue b/app/javascript/dashboard/components-next/NewConversation/components/WhatsappTemplate.vue
index 8e655fcfb..03789839a 100644
--- a/app/javascript/dashboard/components-next/NewConversation/components/WhatsappTemplate.vue
+++ b/app/javascript/dashboard/components-next/NewConversation/components/WhatsappTemplate.vue
@@ -24,9 +24,7 @@ const handleBack = () => {
 </script>
 
 <template>
-  <div
-    class="absolute top-full mt-1.5 max-h-[30rem] overflow-y-auto ltr:left-0 rtl:right-0 flex flex-col gap-4 px-4 pt-6 pb-5 items-start w-[28.75rem] h-auto bg-n-solid-2 border border-n-strong shadow-sm rounded-lg"
-  >
+  <div class="flex flex-col gap-4 px-4 pt-6 pb-5 items-start w-[28.75rem]">
     <div class="w-full">
       <WhatsAppTemplateParser
         :template="template"
diff --git a/app/javascript/dashboard/components-next/popover/Popover.vue b/app/javascript/dashboard/components-next/popover/Popover.vue
index 18e711c12..5b67e572f 100644
--- a/app/javascript/dashboard/components-next/popover/Popover.vue
+++ b/app/javascript/dashboard/components-next/popover/Popover.vue
@@ -12,6 +12,14 @@ const props = defineProps({
     default: 'end',
     validator: v => ['start', 'end'].includes(v),
   },
+  disableMobileView: {
+    type: Boolean,
+    default: false,
+  },
+  showContentBorder: {
+    type: Boolean,
+    default: true,
+  },
 });
 
 const emit = defineEmits(['show', 'hide']);
@@ -22,7 +30,8 @@ const popoverRef = ref(null);
 const mobileContentRef = ref(null);
 
 const breakpoints = useBreakpoints(breakpointsTailwind);
-const isMobile = breakpoints.smaller('md');
+const belowMd = breakpoints.smaller('md');
+const isMobile = computed(() => !props.disableMobileView && belowMd.value);
 const showPopover = computed(() => isActive.value && !isMobile.value);
 
 const { fixedPosition, updatePosition } = useDropdownPosition(
@@ -99,9 +108,13 @@ defineExpose({ show, hide, toggle });
           { ignore: clickOutsideIgnore },
         ]"
         data-popover-content
-        class="relative w-full max-w-lg max-h-[calc(100vh-4rem)] mx-4 overflow-y-auto bg-n-alpha-3 backdrop-blur-[100px] shadow-xl rounded-xl"
+        class="relative flex flex-col w-full max-w-lg max-h-[calc(100vh-4rem)] mx-4 bg-n-alpha-3 backdrop-blur-[100px] shadow-xl rounded-xl"
       >
-        <slot name="content" :hide="hide" />
+        <div
+          class="flex-1 min-h-0 overflow-y-auto overscroll-contain rounded-xl"
+        >
+          <slot name="content" :hide="hide" />
+        </div>
       </div>
     </div>
 
@@ -113,9 +126,14 @@ defineExpose({ show, hide, toggle });
       data-popover-content
       :class="fixedPosition.class"
       :style="fixedPosition.style"
-      class="bg-n-alpha-3 backdrop-blur-[100px] shadow-xl rounded-xl overflow-y-auto max-h-[calc(100vh-2rem)]"
+      class="flex flex-col bg-n-alpha-3 backdrop-blur-[100px] shadow-xl rounded-xl"
     >
-      <slot name="content" :hide="hide" />
+      <div
+        class="flex-1 min-h-0 overflow-y-auto overscroll-contain rounded-xl"
+        :class="{ 'border border-n-strong': showContentBorder }"
+      >
+        <slot name="content" :hide="hide" />
+      </div>
     </div>
   </TeleportWithDirection>
 </template>
diff --git a/app/javascript/dashboard/modules/contact/ContactDeleteModal.vue b/app/javascript/dashboard/modules/contact/ContactDeleteModal.vue
index 3bf48e184..617b0456f 100644
--- a/app/javascript/dashboard/modules/contact/ContactDeleteModal.vue
+++ b/app/javascript/dashboard/modules/contact/ContactDeleteModal.vue
@@ -60,9 +60,7 @@ const onDelete = async hide => {
   <Popover @hide="$emit('close')">
     <slot name="trigger" />
     <template #content="{ hide }">
-      <div
-        class="w-full md:w-80 p-6 flex flex-col gap-4 border-0 md:border rounded-xl md:border-n-strong"
-      >
+      <div class="w-full md:w-80 p-6 flex flex-col gap-4">
         <div class="flex flex-col gap-2">
           <h3 class="text-base font-medium leading-6 text-n-slate-12">
             {{ $t('DELETE_CONTACT.CONFIRM.TITLE') }}
diff --git a/app/javascript/dashboard/modules/contact/ContactMergeModal.vue b/app/javascript/dashboard/modules/contact/ContactMergeModal.vue
index 1a343f777..be06581a6 100644
--- a/app/javascript/dashboard/modules/contact/ContactMergeModal.vue
+++ b/app/javascript/dashboard/modules/contact/ContactMergeModal.vue
@@ -72,9 +72,7 @@ const onMergeContacts = async (parentContactId, hide) => {
   <Popover @hide="$emit('close')">
     <slot name="trigger" />
     <template #content="{ hide }">
-      <div
-        class="w-full md:w-96 p-6 flex flex-col gap-4 border-0 md:border rounded-xl md:border-n-strong"
-      >
+      <div class="w-full md:w-96 p-6 flex flex-col gap-4">
         <div class="flex flex-col gap-2">
           <h3 class="text-base font-medium leading-6 text-n-slate-12">
             {{ $t('MERGE_CONTACTS.TITLE') }}

From ce34f939170216fa481586d11b996b69b01cb384 Mon Sep 17 00:00:00 2001
From: Vishnu Narayanan <iamwishnu@gmail.com>
Date: Wed, 22 Apr 2026 20:36:35 +0530
Subject: [PATCH 6/7] fix: index email subject from conversation for outbound
 messages (#14122)

## Summary

Outbound email messages never populate
`content_attributes.email.subject`. The subject lives only on the parent
conversation's `additional_attributes.mail_subject`. The search index
doc built by `Messages::SearchDataPresenter` pulls from the
message-level field only, so outbound email subjects are unsearchable
for accounts on the advanced_search (Elasticsearch) path.

This change makes the presenter fall back to
`conversation.additional_attributes.mail_subject` when the message-level
subject is blank. Inbound email messages keep their existing behavior
(message-level subject takes precedence).

Closes https://linear.app/chatwoot/issue/CW-6877

## What changes

- `Messages::SearchDataPresenter#content_attributes_data` now falls back
to the conversation's `mail_subject` when the message-level subject is
blank.
- Added specs covering the fallback, precedence, and the neither-set
case.

## What does not change

- No schema changes, no migrations, no backfill of existing OpenSearch
documents.
- Searchkick's `after_commit :reindex_for_search` on `Message` will pick
up the new field for all newly created or updated messages via the
existing indexing path.
- Postgres search path (free accounts, fallback) is untouched. Broader
subject search for those users is a separate follow-up.
---
 .../messages/search_data_presenter.rb         |  3 +-
 .../messages/search_data_presenter_spec.rb    | 29 +++++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/app/presenters/messages/search_data_presenter.rb b/app/presenters/messages/search_data_presenter.rb
index 7a6260686..e90c9b600 100644
--- a/app/presenters/messages/search_data_presenter.rb
+++ b/app/presenters/messages/search_data_presenter.rb
@@ -39,7 +39,8 @@ class Messages::SearchDataPresenter < SimpleDelegator
   end
 
   def content_attributes_data
-    email_subject = content_attributes.dig(:email, :subject)
+    email_subject = content_attributes.dig(:email, :subject).presence ||
+                    conversation.additional_attributes&.dig('mail_subject').presence
     return {} if email_subject.blank?
 
     { email: { subject: email_subject } }
diff --git a/spec/presenters/messages/search_data_presenter_spec.rb b/spec/presenters/messages/search_data_presenter_spec.rb
index 7b3d4acb9..48faec12a 100644
--- a/spec/presenters/messages/search_data_presenter_spec.rb
+++ b/spec/presenters/messages/search_data_presenter_spec.rb
@@ -58,6 +58,35 @@ RSpec.describe Messages::SearchDataPresenter do
       end
     end
 
+    context 'when the message has no email subject but the conversation has a mail_subject' do
+      before do
+        conversation.update!(additional_attributes: { 'mail_subject' => 'Conversation Subject' })
+      end
+
+      it 'falls back to the conversation mail_subject' do
+        content_attrs = presenter.search_data[:content_attributes]
+        expect(content_attrs[:email][:subject]).to eq('Conversation Subject')
+      end
+    end
+
+    context 'when both the message email subject and conversation mail_subject are set' do
+      before do
+        conversation.update!(additional_attributes: { 'mail_subject' => 'Conversation subject' })
+        message.update!(content_attributes: { email: { subject: 'Message subject' } })
+      end
+
+      it 'prefers the message-level email subject' do
+        content_attrs = presenter.search_data[:content_attributes]
+        expect(content_attrs[:email][:subject]).to eq('Message subject')
+      end
+    end
+
+    context 'when neither message nor conversation has an email subject' do
+      it 'omits the email subject from content_attributes' do
+        expect(presenter.search_data[:content_attributes]).to eq({})
+      end
+    end
+
     context 'with campaign and automation data' do
       before do
         message.update(

From 21821652012dbb3af206652e658a96a994645c39 Mon Sep 17 00:00:00 2001
From: Aakash Bakhle <48802744+aakashb95@users.noreply.github.com>
Date: Wed, 22 Apr 2026 23:36:32 +0530
Subject: [PATCH 7/7] feat: sync documents job [AI-142] (#14057)

# Pull Request Template

## Description

Document auto-sync job pipeline without wiring to controllers or FE

Fixes # (issue)

## Type of change

- [x] New feature (non-breaking change which adds functionality)

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide
instructions so we can reproduce. Please also list any relevant details
for your test configuration.
specs and locally

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] Any dependent changes have been merged and published in downstream
modules
---
 .../captain/documents/perform_sync_job.rb     | 97 +++++++++++++++++++
 .../captain/documents/response_builder_job.rb |  2 +-
 enterprise/app/models/captain/document.rb     |  9 ++
 .../captain/documents/single_page_fetcher.rb  | 80 +++++++++++++++
 .../captain/documents/sync_service.rb         | 76 +++++++++++++++
 .../captain/tools/firecrawl_service.rb        | 16 ++-
 .../captain/tools/html_page_parser.rb         | 15 +++
 .../tools/simple_page_crawl_service.rb        |  8 +-
 lib/redis/redis_keys.rb                       |  1 +
 .../models/captain/document_spec.rb           |  5 +
 10 files changed, 303 insertions(+), 6 deletions(-)
 create mode 100644 enterprise/app/jobs/captain/documents/perform_sync_job.rb
 create mode 100644 enterprise/app/services/captain/documents/single_page_fetcher.rb
 create mode 100644 enterprise/app/services/captain/documents/sync_service.rb
 create mode 100644 enterprise/app/services/captain/tools/html_page_parser.rb

diff --git a/enterprise/app/jobs/captain/documents/perform_sync_job.rb b/enterprise/app/jobs/captain/documents/perform_sync_job.rb
new file mode 100644
index 000000000..baa9c03d2
--- /dev/null
+++ b/enterprise/app/jobs/captain/documents/perform_sync_job.rb
@@ -0,0 +1,97 @@
+class Captain::Documents::PerformSyncJob < MutexApplicationJob
+  queue_as :low
+
+  LOCK_TIMEOUT = 10.minutes
+
+  # Safety net for anything we didn't rescue by name — parser bugs, ActiveRecord blips,
+  # random infra issues. Three attempts lets a real hiccup recover. The exhaustion block
+  # absorbs the final exception so Sidekiq doesn't layer its own retry policy on top, and
+  # is the single place we report to Sentry — handle_unexpected_failure logs but does not
+  # capture, so a deterministic bug emits one Sentry event instead of one per attempt.
+  # Goes first because retry_on handlers dispatch bottom-to-top.
+  retry_on StandardError, wait: 5.seconds, attempts: 3 do |job, error|
+    document = job.arguments.first
+    ChatwootExceptionTracker.new(error, account: document.account).capture_exception
+    job.send(:log_sync_outcome, document, result: :unexpected_retry_exhausted,
+                                          error_code: 'sync_error',
+                                          exception_class: error.class.name)
+  end
+
+  # Permanent errors (404, 403, empty content) — no point retrying, discard immediately.
+  # Document is already marked failed by SyncService before the exception reaches here.
+  discard_on(Captain::Documents::SyncService::PermanentSyncError)
+
+  # TransientSyncError is raised by SyncService when the customer's site is unreachable —
+  # timeouts, TLS errors, 5xx, connection drops. Four attempts with backoff gives the site
+  # a chance to recover before we give up.
+  #
+  # The exhaustion block absorbs the exception so it doesn't propagate to Sentry —
+  # site flakiness isn't an application bug.
+  retry_on(
+    Captain::Documents::SyncService::TransientSyncError,
+    wait: ->(executions) { [30.seconds, 2.minutes, 5.minutes][executions - 1] || 5.minutes },
+    attempts: 4
+  ) do |job, error|
+    document = job.arguments.first
+    job.send(:log_sync_outcome, document, result: :transient_retry_exhausted, error_code: error.message)
+  end
+
+  discard_on ActiveJob::DeserializationError
+  discard_on ActiveRecord::RecordNotFound
+
+  def perform(document)
+    start_time = Time.current
+    return if document.pdf_document?
+
+    with_lock(lock_key(document), LOCK_TIMEOUT) do
+      document.update!(sync_status: :syncing, last_sync_attempted_at: Time.current)
+      result = Captain::Documents::SyncService.new(document.reload).perform
+      log_sync_outcome(document, result: result, duration_ms: duration_ms_since(start_time))
+    end
+  rescue LockAcquisitionError
+    log_sync_outcome(document, result: :already_syncing)
+  rescue Captain::Documents::SyncService::PermanentSyncError => e
+    log_failure_and_raise(document, :permanent_failure, e, start_time)
+  rescue Captain::Documents::SyncService::TransientSyncError => e
+    log_failure_and_raise(document, :transient_failure, e, start_time)
+  rescue StandardError => e
+    handle_unexpected_failure(document, e, start_time)
+  end
+
+  private
+
+  def log_sync_outcome(document, **fields)
+    payload = {
+      document_id: document.id,
+      account_id: document.account_id,
+      assistant_id: document.assistant_id
+    }.merge(fields)
+    Rails.logger.info("[Captain::Documents::PerformSyncJob] #{payload.to_json}")
+  end
+
+  def log_failure_and_raise(document, result, error, start_time)
+    log_sync_outcome(document, result: result, error_code: error.message,
+                               duration_ms: duration_ms_since(start_time))
+    raise error
+  end
+
+  def handle_unexpected_failure(document, error, start_time)
+    document.update!(
+      sync_status: :failed,
+      last_sync_error_code: 'sync_error',
+      last_sync_attempted_at: Time.current
+    )
+    log_sync_outcome(document, result: :unexpected_failure, error_code: 'sync_error',
+                               exception_class: error.class.name,
+                               duration_ms: duration_ms_since(start_time))
+    raise error
+  end
+
+  def lock_key(document)
+    format(::Redis::Alfred::CAPTAIN_DOCUMENT_SYNC_MUTEX, document_id: document.id)
+  end
+
+  def duration_ms_since(start_time)
+    ((Time.current - start_time) * 1000).round
+  end
+end
diff --git a/enterprise/app/jobs/captain/documents/response_builder_job.rb b/enterprise/app/jobs/captain/documents/response_builder_job.rb
index 553cec110..60f1fa2cf 100644
--- a/enterprise/app/jobs/captain/documents/response_builder_job.rb
+++ b/enterprise/app/jobs/captain/documents/response_builder_job.rb
@@ -62,7 +62,7 @@ class Captain::Documents::ResponseBuilderJob < ApplicationJob
   end
 
   def reset_previous_responses(response_document)
-    response_document.responses.destroy_all
+    response_document.responses.where(edited: false).destroy_all
   end
 
   def create_response(faq, document)
diff --git a/enterprise/app/models/captain/document.rb b/enterprise/app/models/captain/document.rb
index d8e07a2d9..2abf18437 100644
--- a/enterprise/app/models/captain/document.rb
+++ b/enterprise/app/models/captain/document.rb
@@ -62,6 +62,7 @@ class Captain::Document < ApplicationRecord
 
   def pdf_document?
     return true if pdf_file.attached? && pdf_file.blob.content_type == 'application/pdf'
+    return true if external_link&.start_with?('PDF:')
 
     external_link&.ends_with?('.pdf')
   end
@@ -90,6 +91,14 @@ class Captain::Document < ApplicationRecord
     self.metadata = (metadata || {}).merge('last_sync_error_code' => value)
   end
 
+  def sync_step
+    metadata&.dig('sync_step')
+  end
+
+  def store_sync_step(step)
+    update!(metadata: (metadata || {}).merge('sync_step' => step))
+  end
+
   def openai_file_id
     metadata&.dig('openai_file_id')
   end
diff --git a/enterprise/app/services/captain/documents/single_page_fetcher.rb b/enterprise/app/services/captain/documents/single_page_fetcher.rb
new file mode 100644
index 000000000..115cd55b0
--- /dev/null
+++ b/enterprise/app/services/captain/documents/single_page_fetcher.rb
@@ -0,0 +1,80 @@
+class Captain::Documents::SinglePageFetcher
+  Result = Struct.new(:success, :title, :content, :error_code, keyword_init: true)
+
+  CONTENT_MAX_LENGTH = 200_000
+  TITLE_MAX_LENGTH = 255 # captain_documents.name is a varchar(255)
+
+  def initialize(url)
+    @url = url
+  end
+
+  def fetch
+    result = firecrawl_configured? ? fetch_with_firecrawl : fetch_with_fallback
+    validate_content(result)
+  rescue Net::ReadTimeout, Net::OpenTimeout, Errno::ETIMEDOUT
+    Result.new(success: false, error_code: 'timeout')
+  rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET, OpenSSL::SSL::SSLError
+    Result.new(success: false, error_code: 'fetch_failed')
+  end
+
+  private
+
+  def firecrawl_configured?
+    InstallationConfig.find_by(name: 'CAPTAIN_FIRECRAWL_API_KEY')&.value.present?
+  end
+
+  def fetch_with_firecrawl
+    response = Captain::Tools::FirecrawlService.new.scrape(@url)
+    handle_firecrawl_response(response)
+  end
+
+  def handle_firecrawl_response(response)
+    return Result.new(success: false, error_code: http_error_code(response.code)) unless response.success?
+
+    data = response.parsed_response&.dig('data')
+    target_error = firecrawl_target_error_code(data)
+    return Result.new(success: false, error_code: target_error) if target_error
+
+    Result.new(
+      success: true,
+      title: data&.dig('metadata', 'title')&.truncate(TITLE_MAX_LENGTH, omission: ''),
+      content: data&.dig('markdown')&.truncate(CONTENT_MAX_LENGTH, omission: '')
+    )
+  end
+
+  # Firecrawl returns API 200 even when the scraped page itself failed —
+  # the target page's real status lives in data.metadata.statusCode.
+  def firecrawl_target_error_code(data)
+    status = data&.dig('metadata', 'statusCode')
+    return nil if status.blank? || (200..299).cover?(status)
+
+    http_error_code(status)
+  end
+
+  def fetch_with_fallback
+    response = HTTParty.get(@url)
+    return Result.new(success: false, error_code: http_error_code(response.code)) unless response.success?
+
+    parser = Captain::Tools::HtmlPageParser.new(response.body)
+    Result.new(
+      success: true,
+      title: parser.title&.truncate(TITLE_MAX_LENGTH, omission: ''),
+      content: parser.body_markdown&.truncate(CONTENT_MAX_LENGTH, omission: '')
+    )
+  end
+
+  def validate_content(result)
+    return result unless result.success && result.content.blank?
+
+    Result.new(success: false, error_code: 'content_empty')
+  end
+
+  def http_error_code(status_code)
+    case status_code
+    when 404 then 'not_found'
+    when 401, 403 then 'access_denied'
+    when 408, 504 then 'timeout'
+    else 'fetch_failed'
+    end
+  end
+end
diff --git a/enterprise/app/services/captain/documents/sync_service.rb b/enterprise/app/services/captain/documents/sync_service.rb
new file mode 100644
index 000000000..5dcb52447
--- /dev/null
+++ b/enterprise/app/services/captain/documents/sync_service.rb
@@ -0,0 +1,76 @@
+class Captain::Documents::SyncService
+  class PermanentSyncError < StandardError
+  end
+
+  class TransientSyncError < StandardError
+  end
+
+  PERMANENT_ERROR_CODES = %w[not_found access_denied content_empty].freeze
+
+  def initialize(document)
+    @document = document
+  end
+
+  def perform
+    @document.store_sync_step('fetching')
+    result = Captain::Documents::SinglePageFetcher.new(@document.external_link).fetch
+
+    unless result.success
+      mark_failed(result.error_code)
+      raise_for_error_code(result.error_code)
+    end
+
+    @document.store_sync_step('comparing')
+    fingerprint = compute_fingerprint(result.content)
+
+    if fingerprint == @document.content_fingerprint
+      mark_synced
+      return :unchanged
+    end
+
+    @document.store_sync_step('updating')
+    update_content(result, fingerprint)
+    :updated
+  end
+
+  private
+
+  def compute_fingerprint(content)
+    Digest::SHA256.hexdigest(content.gsub(/\s+/, ' ').strip)
+  end
+
+  def mark_failed(error_code)
+    @document.update!(
+      sync_status: :failed,
+      last_sync_error_code: error_code,
+      last_sync_attempted_at: Time.current
+    )
+  end
+
+  def mark_synced
+    @document.update!(
+      sync_status: :synced,
+      last_synced_at: Time.current,
+      last_sync_attempted_at: Time.current,
+      last_sync_error_code: nil
+    )
+  end
+
+  def update_content(result, fingerprint)
+    @document.update!(
+      content: result.content,
+      name: result.title.presence || @document.name,
+      content_fingerprint: fingerprint,
+      sync_status: :synced,
+      last_synced_at: Time.current,
+      last_sync_attempted_at: Time.current,
+      last_sync_error_code: nil
+    )
+  end
+
+  def raise_for_error_code(error_code)
+    raise PermanentSyncError, error_code if PERMANENT_ERROR_CODES.include?(error_code)
+
+    raise TransientSyncError, error_code
+  end
+end
diff --git a/enterprise/app/services/captain/tools/firecrawl_service.rb b/enterprise/app/services/captain/tools/firecrawl_service.rb
index 397c3ad63..fc7448593 100644
--- a/enterprise/app/services/captain/tools/firecrawl_service.rb
+++ b/enterprise/app/services/captain/tools/firecrawl_service.rb
@@ -1,4 +1,6 @@
 class Captain::Tools::FirecrawlService
+  BASE_URL = 'https://api.firecrawl.dev/v1'.freeze
+
   def initialize
     @api_key = InstallationConfig.find_by!(name: 'CAPTAIN_FIRECRAWL_API_KEY').value
     raise 'Missing API key' if @api_key.empty?
@@ -6,7 +8,7 @@ class Captain::Tools::FirecrawlService
 
   def perform(url, webhook_url, crawl_limit = 10)
     HTTParty.post(
-      'https://api.firecrawl.dev/v1/crawl',
+      "#{BASE_URL}/crawl",
       body: crawl_payload(url, webhook_url, crawl_limit),
       headers: headers
     )
@@ -14,6 +16,14 @@ class Captain::Tools::FirecrawlService
     raise "Failed to crawl URL: #{e.message}"
   end
 
+  def scrape(url)
+    HTTParty.post(
+      "#{BASE_URL}/scrape",
+      body: scrape_payload(url),
+      headers: headers
+    )
+  end
+
   private
 
   def crawl_payload(url, webhook_url, crawl_limit)
@@ -31,6 +41,10 @@ class Captain::Tools::FirecrawlService
     }.to_json
   end
 
+  def scrape_payload(url)
+    { url: url, formats: ['markdown'], excludeTags: ['iframe'] }.to_json
+  end
+
   def headers
     {
       'Authorization' => "Bearer #{@api_key}",
diff --git a/enterprise/app/services/captain/tools/html_page_parser.rb b/enterprise/app/services/captain/tools/html_page_parser.rb
new file mode 100644
index 000000000..a7afb52cf
--- /dev/null
+++ b/enterprise/app/services/captain/tools/html_page_parser.rb
@@ -0,0 +1,15 @@
+class Captain::Tools::HtmlPageParser
+  attr_reader :doc
+
+  def initialize(html)
+    @doc = Nokogiri::HTML(html)
+  end
+
+  def title
+    @doc.at_xpath('//title')&.text&.strip
+  end
+
+  def body_markdown
+    ReverseMarkdown.convert(@doc.at_xpath('//body'), unknown_tags: :bypass, github_flavored: true)
+  end
+end
diff --git a/enterprise/app/services/captain/tools/simple_page_crawl_service.rb b/enterprise/app/services/captain/tools/simple_page_crawl_service.rb
index 65731ad90..5eaee6e5e 100644
--- a/enterprise/app/services/captain/tools/simple_page_crawl_service.rb
+++ b/enterprise/app/services/captain/tools/simple_page_crawl_service.rb
@@ -3,7 +3,8 @@ class Captain::Tools::SimplePageCrawlService
 
   def initialize(external_link)
     @external_link = external_link
-    @doc = Nokogiri::HTML(HTTParty.get(external_link).body)
+    @parser = Captain::Tools::HtmlPageParser.new(HTTParty.get(external_link).body)
+    @doc = @parser.doc
   end
 
   def page_links
@@ -11,12 +12,11 @@ class Captain::Tools::SimplePageCrawlService
   end
 
   def page_title
-    title_element = @doc.at_xpath('//title')
-    title_element&.text&.strip
+    @parser.title
   end
 
   def body_text_content
-    ReverseMarkdown.convert @doc.at_xpath('//body'), unknown_tags: :bypass, github_flavored: true
+    @parser.body_markdown
   end
 
   def meta_description
diff --git a/lib/redis/redis_keys.rb b/lib/redis/redis_keys.rb
index 59e33036d..893fb50ef 100644
--- a/lib/redis/redis_keys.rb
+++ b/lib/redis/redis_keys.rb
@@ -44,6 +44,7 @@ module Redis::RedisKeys
   SLACK_MESSAGE_MUTEX = 'SLACK_MESSAGE_LOCK::%<conversation_id>s::%<reference_id>s'.freeze
   EMAIL_MESSAGE_MUTEX = 'EMAIL_CHANNEL_LOCK::%<inbox_id>s'.freeze
   CRM_PROCESS_MUTEX = 'CRM_PROCESS_MUTEX::%<hook_id>s'.freeze
+  CAPTAIN_DOCUMENT_SYNC_MUTEX = 'CAPTAIN_DOCUMENT_SYNC_LOCK::%<document_id>s'.freeze
 
   ## Auto Assignment Keys
   # Track conversation assignments to agents for rate limiting
diff --git a/spec/enterprise/models/captain/document_spec.rb b/spec/enterprise/models/captain/document_spec.rb
index e6543e0d7..af6c1cb58 100644
--- a/spec/enterprise/models/captain/document_spec.rb
+++ b/spec/enterprise/models/captain/document_spec.rb
@@ -55,6 +55,11 @@ RSpec.describe Captain::Document, type: :model do
         expect(doc.pdf_document?).to be true
       end
 
+      it 'returns true for PDF:-prefixed external links even when the blob is missing' do
+        doc = build(:captain_document, external_link: 'PDF: report_20250101120000')
+        expect(doc.pdf_document?).to be true
+      end
+
       it 'returns false for non-PDF documents' do
         doc = build(:captain_document, external_link: 'https://example.com')
         expect(doc.pdf_document?).to be false