feat: sign webhooks for API channel and agentbots (#13892)

Account webhooks sign outgoing payloads with HMAC-SHA256, but agent bot
and API inbox webhooks were delivered unsigned. This PR adds the same
signing to both.

Each model gets a dedicated `secret` column rather than reusing the
agent bot's `access_token` (for API auth back into Chatwoot) or the API
inbox's `hmac_token` (for inbound contact identity verification). These
serve different trust boundaries and shouldn't be coupled — rotating a
signing secret shouldn't invalidate API access or contact verification.

The existing `Webhooks::Trigger` already signs when a secret is present,
so the backend change is just passing `secret:` through to the jobs.
Shared token logic is extracted into a `WebhookSecretable` concern
included by `Webhook`, `AgentBot`, and `Channel::Api`. The frontend
reuses the existing `AccessToken` component for secret display. Secrets
are admin-only and excluded from enterprise audit logs.

### How to test

Point an agent bot or API inbox webhook URL at a request inspector. Send
a message and verify `X-Chatwoot-Signature` and `X-Chatwoot-Timestamp`
headers are present. Reset the secret from settings and confirm
subsequent deliveries use the new value.

---------

Co-authored-by: Sojan Jose <sojan@pepalo.com>

app/controllers/api/v1/accounts/agent_bots_controller.rb

@@ -34,6 +34,10 @@ class Api::V1::Accounts::AgentBotsController < Api::V1::Accounts::BaseController
     @agent_bot.reload
   end
 
+  def reset_secret
+    @agent_bot.reset_secret!
+  end
+
   private
 
   def agent_bot

app/controllers/api/v1/accounts/inboxes_controller.rb

@@ -66,6 +66,12 @@ class Api::V1::Accounts::InboxesController < Api::V1::Accounts::BaseController
     head :ok
   end
 
+  def reset_secret
+    return head :not_found unless @inbox.api?
+
+    @inbox.channel.reset_secret!
+  end
+
   def destroy
     ::DeleteObjectJob.perform_later(@inbox, Current.user, request.ip) if @inbox.present?
     render status: :ok, json: { message: I18n.t('messages.inbox_deletetion_response') }

app/javascript/dashboard/api/agentBots.js

@@ -25,6 +25,10 @@ class AgentBotsAPI extends ApiClient {
   resetAccessToken(botId) {
     return axios.post(`${this.url}/${botId}/reset_access_token`);
   }
+
+  resetSecret(botId) {
+    return axios.post(`${this.url}/${botId}/reset_secret`);
+  }
 }
 
 export default new AgentBotsAPI();

app/javascript/dashboard/api/inboxes.js

@@ -48,6 +48,10 @@ class Inboxes extends CacheEnabledApiClient {
       template,
     });
   }
+
+  resetSecret(inboxId) {
+    return axios.post(`${this.url}/${inboxId}/reset_secret`);
+  }
 }
 
 export default new Inboxes();

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

@@ -63,6 +63,16 @@
         "ERROR_MESSAGE": "Could not update bot. Please try again."
       }
     },
+    "SECRET": {
+      "LABEL": "Webhook Secret",
+      "COPY": "Copy secret to clipboard",
+      "COPY_SUCCESS": "Secret copied to clipboard",
+      "TOGGLE": "Toggle secret visibility",
+      "CREATED_DESC": "Use the secret below to verify webhook signatures. Please copy it now, you can also find it later in the bot settings.",
+      "DONE": "Done",
+      "RESET_SUCCESS": "Webhook secret regenerated successfully",
+      "RESET_ERROR": "Unable to regenerate webhook secret. Please try again"
+    },
     "ACCESS_TOKEN": {
       "TITLE": "Access Token",
       "DESCRIPTION": "Copy the access token and save it securely",

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

@@ -86,6 +86,14 @@
           "PLACEHOLDER": "Please enter your Webhook URL",
           "ERROR": "Please enter a valid URL"
         },
+        "CHANNEL_WEBHOOK_SECRET": {
+          "LABEL": "Webhook Secret",
+          "COPY": "Copy secret to clipboard",
+          "COPY_SUCCESS": "Secret copied to clipboard",
+          "TOGGLE": "Toggle secret visibility",
+          "RESET_SUCCESS": "Webhook secret regenerated successfully",
+          "RESET_ERROR": "Unable to regenerate webhook secret. Please try again"
+        },
         "CHANNEL_DOMAIN": {
           "LABEL": "Website Domain",
           "PLACEHOLDER": "Enter your website domain (eg: acme.com)"

app/javascript/dashboard/routes/dashboard/settings/agentBots/components/AgentBotModal.vue

@@ -47,6 +47,7 @@ const formState = reactive({
 
 const [showAccessToken, toggleAccessToken] = useToggle();
 const accessToken = ref('');
+const botSecret = ref('');
 
 const v$ = useVuelidate(
   {
@@ -179,15 +180,21 @@ const handleSubmit = async () => {
       : t('AGENT_BOTS.EDIT.API.SUCCESS_MESSAGE');
     useAlert(alertKey);
 
-    // Show access token after creation
+    // Show access token and secret after creation
     if (isCreate) {
-      const { access_token: responseAccessToken, id } = response || {};
+      const {
+        access_token: responseAccessToken,
+        secret: responseSecret,
+        id,
+      } = response || {};
 
       if (id && responseAccessToken) {
         accessToken.value = responseAccessToken;
+        botSecret.value = responseSecret || '';
         toggleAccessToken(true);
       } else {
         accessToken.value = '';
+        botSecret.value = '';
         dialogRef.value.close();
       }
     } else {
@@ -212,14 +219,16 @@ const initializeForm = () => {
       thumbnail,
       bot_config: botConfig,
       access_token: botAccessToken,
+      secret: botSecretValue,
     } = props.selectedBot;
     formState.botName = name || '';
     formState.botDescription = description || '';
     formState.botUrl = botUrl || botConfig?.webhook_url || '';
     formState.botAvatarUrl = thumbnail || '';
 
-    if (botAccessToken && props.type === MODAL_TYPES.EDIT) {
-      accessToken.value = botAccessToken;
+    if (props.type === MODAL_TYPES.EDIT) {
+      if (botAccessToken) accessToken.value = botAccessToken;
+      if (botSecretValue) botSecret.value = botSecretValue;
     }
   } else {
     resetForm();
@@ -231,6 +240,24 @@ const onCopyToken = async value => {
   useAlert(t('AGENT_BOTS.ACCESS_TOKEN.COPY_SUCCESSFUL'));
 };
 
+const onCopySecret = async value => {
+  await copyTextToClipboard(value || botSecret.value);
+  useAlert(t('AGENT_BOTS.SECRET.COPY_SUCCESS'));
+};
+
+const onResetSecret = async () => {
+  const response = await store.dispatch(
+    'agentBots/resetSecret',
+    props.selectedBot.id
+  );
+  if (response) {
+    botSecret.value = response.secret;
+    useAlert(t('AGENT_BOTS.SECRET.RESET_SUCCESS'));
+  } else {
+    useAlert(t('AGENT_BOTS.SECRET.RESET_ERROR'));
+  }
+};
+
 const onResetToken = async () => {
   const response = await store.dispatch(
     'agentBots/resetAccessToken',
@@ -247,6 +274,7 @@ const onResetToken = async () => {
 const closeModal = () => {
   if (!showAccessToken.value) v$.value?.$reset();
   accessToken.value = '';
+  botSecret.value = '';
   toggleAccessToken(false);
 };
 
@@ -318,6 +346,20 @@ defineExpose({ dialogRef });
         />
       </div>
 
+      <div
+        v-if="botSecret && type === MODAL_TYPES.EDIT"
+        class="flex flex-col gap-1"
+      >
+        <label class="mb-0.5 text-sm font-medium text-n-slate-12">
+          {{ $t('AGENT_BOTS.SECRET.LABEL') }}
+        </label>
+        <AccessToken
+          :value="botSecret"
+          @on-copy="onCopySecret"
+          @on-reset="onResetSecret"
+        />
+      </div>
+
       <div v-if="showAccessTokenInput" class="flex flex-col gap-1">
         <label
           v-if="type === MODAL_TYPES.EDIT"
@@ -339,6 +381,23 @@ defineExpose({ dialogRef });
         />
       </div>
 
+      <div
+        v-if="botSecret && showAccessToken && type === MODAL_TYPES.CREATE"
+        class="flex flex-col gap-1"
+      >
+        <p class="text-sm text-n-slate-11">
+          {{ $t('AGENT_BOTS.SECRET.CREATED_DESC') }}
+        </p>
+        <label class="mb-0.5 text-sm font-medium text-n-slate-12">
+          {{ $t('AGENT_BOTS.SECRET.LABEL') }}
+        </label>
+        <AccessToken
+          :value="botSecret"
+          :show-reset-button="false"
+          @on-copy="onCopySecret"
+        />
+      </div>
+
       <div class="flex items-center justify-end w-full gap-2 px-0 py-2">
         <NextButton
           faded

app/javascript/dashboard/routes/dashboard/settings/inbox/Settings.vue

@@ -38,6 +38,8 @@ import Editor from 'dashboard/components-next/Editor/Editor.vue';
 import ColorPicker from 'dashboard/components-next/colorpicker/ColorPicker.vue';
 import SelectInput from 'dashboard/components-next/select/Select.vue';
 import Widget from 'dashboard/modules/widget-preview/components/Widget.vue';
+import AccessToken from 'dashboard/routes/dashboard/settings/profile/AccessToken.vue';
+import { copyTextToClipboard } from 'shared/helpers/clipboard';
 
 export default {
   components: {
@@ -69,6 +71,7 @@ export default {
     SelectInput,
     AccountHealth,
     Widget,
+    AccessToken,
   },
   mixins: [inboxMixin],
   setup() {
@@ -362,6 +365,33 @@ export default {
     this.fetchSharedData();
   },
   methods: {
+    async copyWebhookSecret(value) {
+      await copyTextToClipboard(value);
+      useAlert(
+        this.$t(
+          'INBOX_MGMT.ADD.WEBSITE_CHANNEL.CHANNEL_WEBHOOK_SECRET.COPY_SUCCESS'
+        )
+      );
+    },
+    async resetWebhookSecret() {
+      const response = await this.$store.dispatch(
+        'inboxes/resetSecret',
+        this.inbox.id
+      );
+      if (response) {
+        useAlert(
+          this.$t(
+            'INBOX_MGMT.ADD.WEBSITE_CHANNEL.CHANNEL_WEBHOOK_SECRET.RESET_SUCCESS'
+          )
+        );
+      } else {
+        useAlert(
+          this.$t(
+            'INBOX_MGMT.ADD.WEBSITE_CHANNEL.CHANNEL_WEBHOOK_SECRET.RESET_ERROR'
+          )
+        );
+      }
+    },
     fetchSharedData() {
       this.$store.dispatch('agents/get');
       this.$store.dispatch('teams/get');
@@ -714,6 +744,21 @@ export default {
               />
             </SettingsFieldSection>
 
+            <SettingsFieldSection
+              v-if="isAPIInbox && inbox.secret"
+              :label="
+                $t(
+                  'INBOX_MGMT.ADD.WEBSITE_CHANNEL.CHANNEL_WEBHOOK_SECRET.LABEL'
+                )
+              "
+            >
+              <AccessToken
+                :value="inbox.secret"
+                @on-copy="copyWebhookSecret"
+                @on-reset="resetWebhookSecret"
+              />
+            </SettingsFieldSection>
+
             <SettingsFieldSection
               v-if="isAWebWidgetInbox"
               :label="$t('INBOX_MGMT.ADD.WEBSITE_CHANNEL.CHANNEL_DOMAIN.LABEL')"

app/javascript/dashboard/store/modules/agentBots.js

@@ -183,6 +183,17 @@ export const actions = {
       return null;
     }
   },
+
+  resetSecret: async ({ commit }, botId) => {
+    try {
+      const response = await AgentBotsAPI.resetSecret(botId);
+      commit(types.EDIT_AGENT_BOT, response.data);
+      return response.data;
+    } catch (error) {
+      throwErrorMessage(error);
+      return null;
+    }
+  },
 };
 
 export const mutations = {

app/javascript/dashboard/store/modules/inboxes.js

@@ -366,6 +366,16 @@ export const actions = {
     );
     return response.data;
   },
+  resetSecret: async ({ commit }, inboxId) => {
+    try {
+      const response = await InboxesAPI.resetSecret(inboxId);
+      commit(types.default.EDIT_INBOXES, response.data);
+      return response.data;
+    } catch (error) {
+      throwErrorMessage(error);
+      return null;
+    }
+  },
 };
 
 export const mutations = {

app/jobs/agent_bots/webhook_job.rb

@@ -2,11 +2,13 @@ class AgentBots::WebhookJob < WebhookJob
   queue_as :high
   retry_on RestClient::TooManyRequests, RestClient::InternalServerError, wait: 3.seconds, attempts: 3 do |job, error|
     url, payload, webhook_type = job.arguments
-    Webhooks::Trigger.new(url, payload, webhook_type || :agent_bot_webhook).handle_failure(error)
+    kwargs = job.arguments.last.is_a?(Hash) ? job.arguments.last : {}
+    Webhooks::Trigger.new(url, payload, webhook_type || :agent_bot_webhook, secret: kwargs[:secret],
+                                                                            delivery_id: kwargs[:delivery_id]).handle_failure(error)
   end
 
-  def perform(url, payload, webhook_type = :agent_bot_webhook)
-    super(url, payload, webhook_type)
+  def perform(url, payload, webhook_type = :agent_bot_webhook, secret: nil, delivery_id: nil)
+    super(url, payload, webhook_type, secret: secret, delivery_id: delivery_id)
   rescue RestClient::TooManyRequests, RestClient::InternalServerError => e
     Rails.logger.warn("[AgentBots::WebhookJob] attempt #{executions} failed #{e.class.name} payload=#{payload.to_json}")
     raise

app/listeners/agent_bot_listener.rb

@@ -76,6 +76,7 @@ class AgentBotListener < BaseListener
   def process_webhook_bot_event(agent_bot, payload)
     return if agent_bot.outgoing_url.blank?
 
-    AgentBots::WebhookJob.perform_later(agent_bot.outgoing_url, payload)
+    AgentBots::WebhookJob.perform_later(agent_bot.outgoing_url, payload, :agent_bot_webhook,
+                                        secret: agent_bot.secret, delivery_id: SecureRandom.uuid)
   end
 end

app/listeners/webhook_listener.rb

@@ -122,7 +122,7 @@ class WebhookListener < BaseListener
     return if inbox.channel.webhook_url.blank?
 
     WebhookJob.perform_later(inbox.channel.webhook_url, payload, :api_inbox_webhook,
-                             delivery_id: SecureRandom.uuid)
+                             secret: inbox.channel.secret, delivery_id: SecureRandom.uuid)
   end
 
   def deliver_webhook_payloads(payload, inbox)

app/models/agent_bot.rb

@@ -8,6 +8,7 @@
 #  description  :string
 #  name         :string
 #  outgoing_url :string
+#  secret       :string
 #  created_at   :datetime         not null
 #  updated_at   :datetime         not null
 #  account_id   :bigint
@@ -21,6 +22,8 @@ class AgentBot < ApplicationRecord
   include AccessTokenable
   include Avatarable
 
+  include WebhookSecretable
+
   scope :accessible_to, lambda { |account|
     account_id = account&.id
     where(account_id: [nil, account_id])
@@ -63,3 +66,5 @@ class AgentBot < ApplicationRecord
     account.nil?
   end
 end
+
+AgentBot.include_mod_with('Audit::AgentBot')

app/models/channel/api.rb

@@ -7,6 +7,7 @@
 #  hmac_mandatory        :boolean          default(FALSE)
 #  hmac_token            :string
 #  identifier            :string
+#  secret                :string
 #  webhook_url           :string
 #  created_at            :datetime         not null
 #  updated_at            :datetime         not null
@@ -26,6 +27,7 @@ class Channel::Api < ApplicationRecord
 
   has_secure_token :identifier
   has_secure_token :hmac_token
+  include WebhookSecretable
   validate :ensure_valid_agent_reply_time_window
   validates :webhook_url, length: { maximum: Limits::URL_LENGTH_LIMIT }
 

app/models/concerns/webhook_secretable.rb

@@ -0,0 +1,13 @@
+module WebhookSecretable
+  extend ActiveSupport::Concern
+
+  included do
+    has_secure_token :secret
+    encrypts :secret if Chatwoot.encryption_configured?
+  end
+
+  def reset_secret!
+    regenerate_secret
+    reload
+  end
+end

app/models/webhook.rb

@@ -22,8 +22,7 @@ class Webhook < ApplicationRecord
   belongs_to :account
   belongs_to :inbox, optional: true
 
-  has_secure_token :secret
-  encrypts :secret if Chatwoot.encryption_configured?
+  include WebhookSecretable
 
   validates :account_id, presence: true
   validates :url, uniqueness: { scope: [:account_id] }, format: URI::DEFAULT_PARSER.make_regexp(%w[http https])

app/policies/agent_bot_policy.rb

@@ -26,4 +26,8 @@ class AgentBotPolicy < ApplicationPolicy
   def reset_access_token?
     @account_user.administrator?
   end
+
+  def reset_secret?
+    @account_user.administrator?
+  end
 end

app/policies/inbox_policy.rb

@@ -65,4 +65,8 @@ class InboxPolicy < ApplicationPolicy
   def health?
     @account_user.administrator?
   end
+
+  def reset_secret?
+    @account_user.administrator?
+  end
 end

app/views/api/v1/accounts/agent_bots/reset_secret.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/agent_bot', formats: [:json], resource: AgentBotPresenter.new(@agent_bot)

app/views/api/v1/accounts/inboxes/reset_secret.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/inbox', formats: [:json], resource: @inbox

app/views/api/v1/models/_agent_bot.json.jbuilder

@@ -7,4 +7,5 @@ json.bot_type resource.bot_type
 json.bot_config resource.bot_config
 json.account_id resource.account_id
 json.access_token resource.access_token if resource.access_token.present?
+json.secret resource.secret if !resource.system_bot? && Current.account_user&.administrator?
 json.system_bot resource.system_bot?

app/views/api/v1/models/_inbox.json.jbuilder

@@ -113,6 +113,7 @@ end
 ## API Channel Attributes
 if resource.api?
   json.hmac_token resource.channel.try(:hmac_token) if Current.account_user&.administrator?
+  json.secret resource.channel.try(:secret) if Current.account_user&.administrator?
   json.webhook_url resource.channel.try(:webhook_url)
   json.inbox_identifier resource.channel.try(:identifier)
   json.additional_attributes resource.channel.try(:additional_attributes)