feat(webhooks): Emit inbox_updated when an inbox is disconnected (#14504)

Chatwoot now lets external apps know when an inbox loses its connection
and needs re-authentication. When a channel's authorization expires (for
example, an email inbox disconnects), Chatwoot fires an `inbox_updated`
webhook reflecting the new `reauthorization_required` status, and fires
it again once the inbox is re-authenticated. Integrators can keep their
own view of which inboxes are healthy without polling the API.

This is gated behind the `ENABLE_INBOX_EVENTS` installation flag — the
**Inbox updated** webhook subscription only appears in the dashboard
when that flag is enabled, so no event is offered that the backend
wouldn't dispatch.

Fixes
https://linear.app/chatwoot/issue/CW-7148/emit-inbox-webhook-when-an-inbox-is-disconnected

## How to test

1. Set `ENABLE_INBOX_EVENTS=true` and restart the app.
2. In **Settings → Integrations → Webhooks**, add a webhook and
subscribe to **Inbox updated**.
3. Disconnect an inbox — let an email/Instagram channel hit its
auth-error threshold, or run `inbox.channel.prompt_reauthorization!` in
a console.
4. The endpoint receives an `inbox_updated` event whose
`changed_attributes` shows `reauthorization_required` flipping to
`true`.
5. Re-authenticate the inbox (or run `inbox.channel.reauthorized!`) —
the endpoint receives the `true → false` transition.
6. Confirm the **Inbox updated** option is hidden when
`ENABLE_INBOX_EVENTS` is unset.

---------

Co-authored-by: Muhsin <12408980+muhsin-k@users.noreply.github.com>

app/javascript/dashboard/composables/useConfig.js

@@ -36,11 +36,18 @@ export function useConfig() {
    */
   const enterprisePlanName = config.enterprisePlanName;
 
+  /**
+   * Indicates whether inbox webhook events (ENABLE_INBOX_EVENTS) are enabled.
+   * @type {boolean}
+   */
+  const inboxEventsEnabled = config.inboxEventsEnabled === 'true';
+
   return {
     hostURL,
     vapidPublicKey,
     enabledLanguages,
     isEnterprise,
     enterprisePlanName,
+    inboxEventsEnabled,
   };
 }

app/javascript/dashboard/i18n/locale/en/integrations.json

@@ -57,7 +57,8 @@
             "CONTACT_CREATED": "Contact created",
             "CONTACT_UPDATED": "Contact updated",
             "CONVERSATION_TYPING_ON": "Conversation Typing On",
-            "CONVERSATION_TYPING_OFF": "Conversation Typing Off"
+            "CONVERSATION_TYPING_OFF": "Conversation Typing Off",
+            "INBOX_UPDATED": "Inbox updated"
           }
         },
         "NAME": {

app/javascript/dashboard/routes/dashboard/settings/integrations/Webhooks/WebhookForm.vue

@@ -5,6 +5,7 @@ import wootConstants from 'dashboard/constants/globals';
 import { getI18nKey } from 'dashboard/routes/dashboard/settings/helper/settingsHelper';
 import { copyTextToClipboard } from 'shared/helpers/clipboard';
 import { useAlert } from 'dashboard/composables';
+import { useConfig } from 'dashboard/composables/useConfig';
 import NextButton from 'dashboard/components-next/button/Button.vue';
 
 const { EXAMPLE_WEBHOOK_URL } = wootConstants;
@@ -55,12 +56,15 @@ export default {
     },
   },
   data() {
+    const { inboxEventsEnabled } = useConfig();
     return {
       url: this.value.url || '',
       name: this.value.name || '',
       subscriptions: this.value.subscriptions || [],
       secretVisible: false,
-      supportedWebhookEvents: SUPPORTED_WEBHOOK_EVENTS,
+      supportedWebhookEvents: inboxEventsEnabled
+        ? [...SUPPORTED_WEBHOOK_EVENTS, 'inbox_updated']
+        : SUPPORTED_WEBHOOK_EVENTS,
     };
   },
   computed: {

app/models/concerns/reauthorizable.rb

@@ -37,11 +37,14 @@ module Reauthorizable
   # Performed automatically if error threshold is breached
   # could used to manually prompt reauthorization if auth scope changes
   def prompt_reauthorization!
+    state_changed = !reauthorization_required?
+
     ::Redis::Alfred.set(reauthorization_required_key, true)
 
     reauthorization_handlers[self.class.name]&.call(self)
 
     invalidate_inbox_cache unless instance_of?(::AutomationRule)
+    dispatch_inbox_reauthorization_event(true) if state_changed
   end
 
   def process_integration_hook_reauthorization_emails
@@ -63,14 +66,24 @@ module Reauthorizable
 
   # call this after you successfully Reauthorized the object in UI
   def reauthorized!
+    state_changed = reauthorization_required?
+
     ::Redis::Alfred.delete(authorization_error_count_key)
     ::Redis::Alfred.delete(reauthorization_required_key)
 
     invalidate_inbox_cache unless instance_of?(::AutomationRule)
+    dispatch_inbox_reauthorization_event(false) if state_changed
   end
 
   private
 
+  def dispatch_inbox_reauthorization_event(reauthorization_required)
+    return unless respond_to?(:inbox)
+    return if inbox.blank?
+
+    inbox.dispatch_reauthorization_event(reauthorization_required)
+  end
+
   def reauthorization_handlers
     {
       'Integrations::Hook' => ->(obj) { obj.process_integration_hook_reauthorization_emails },

app/models/inbox.rb

@@ -207,6 +207,15 @@ class Inbox < ApplicationRecord
     account.feature_enabled?('assignment_v2')
   end
 
+  # Callers (Reauthorizable) only invoke this on a real transition, so the previous
+  # value is always the inverse of the new boolean value.
+  def dispatch_reauthorization_event(reauthorization_required)
+    return if ENV['ENABLE_INBOX_EVENTS'].blank?
+
+    changed_attributes = { reauthorization_required: [!reauthorization_required, reauthorization_required] }
+    Rails.configuration.dispatcher.dispatch(INBOX_UPDATED, Time.zone.now, inbox: self, changed_attributes: changed_attributes)
+  end
+
   private
 
   def default_name_for_blank_name

app/presenters/inbox/event_data_presenter.rb

@@ -23,7 +23,7 @@ class Inbox::EventDataPresenter < SimpleDelegator
       timezone: timezone,
       out_of_office_message: out_of_office_message,
       working_hours_enabled: working_hours_enabled,
-      working_hours: working_hours,
+      working_hours: working_hours.as_json,
 
       created_at: created_at,
       updated_at: updated_at,

app/views/layouts/vueapp.html.erb

@@ -55,6 +55,7 @@
         <% end %>
         enabledLanguages: <%= available_locales_with_name.to_json.html_safe %>,
         helpUrls: <%= feature_help_urls.to_json.html_safe %>,
+        inboxEventsEnabled: '<%= ENV['ENABLE_INBOX_EVENTS'].present? %>',
         selectedLocale: '<%= I18n.locale %>'
       }
       window.globalConfig = <%= raw @global_config.to_json %>