assistant-storefront/WEBHOOK_TROUBLESHOOTING.md

Webhook 不触发问题排查

快速检查步骤

1. 确认服务器已重启 ⚠️

重要: 修改代码后必须重启服务器！

# 如果使用 overmind
overmind restart web

# 或直接重启 Rails server
# Ctrl+C 然后重新启动
bundle exec rails server

2. 运行调试脚本

cd /home/lxj/project/chatwoot-develop
bundle exec rails c
# 然后在 console 中执行:
load 'debug_webhook.rb'

3. 检查 Webhook 配置

在 Rails console 中执行：

account = Account.find(2)
webhooks = account.webhooks

# 检查数量
puts "Webhooks 数量: #{webhooks.count}"

# 查看配置
webhooks.each do |w|
  puts "ID: #{w.id}"
  puts "URL: #{w.webhook_url}"
  puts "启用: #{w.active}"
  puts "订阅: #{w.subscriptions.inspect}"
end

预期结果:

• active: true (必须启用)
• subscriptions 包含 'message_created' (必须订阅)

4. 手动触发 Webhook 测试

bundle exec rails c
# 然后执行:
load 'test_webhook_manual.rb'

这会：

• 查找最近的 search_image 消息
• 手动构建 webhook payload
• 直接触发 webhook 发送
• 显示结果

5. 查看 Webhook 日志

# 最近的日志
logs = Account.find(2).webhook_logs.order(created_at: :desc).limit(10)

logs.each do |log|
  puts "#{log.created_at} - #{log.event_type} - #{log.status}"
  puts "响应码: #{log.response_code}"
  puts "错误: #{log.error_message}" if log.error_message
  puts "---"
end

6. 检查最近的消息

# 查找 search_image 消息
messages = Message.where(content_type: 'search_image').order(created_at: :desc).limit(5)

messages.each do |msg|
  puts "ID: #{msg.id}"
  puts "content: '#{msg.content}'"
  puts "content_type: #{msg.content_type}"
  puts "创建时间: #{msg.created_at}"
  puts "---"
end

---

常见问题和解决方案

问题 1: 没有配置 Webhook

症状: webhooks.count == 0

解决:

# 创建 Webhook (使用 webhook.site 测试)
account = Account.find(2)

# 1. 访问 https://webhook.site 获取一个临时 URL
# 2. 创建 Webhook 指向该 URL
account.webhooks.create!(
  webhook_url: 'https://webhook.site/your-uuid-here',  # 替换为实际 URL
  subscriptions: ['conversation_created', 'message_created', 'message_updated'],
  active: true
)

问题 2: Webhook 未启用

症状: webhook.active == false

解决:

webhook = Webhook.find(1)
webhook.update!(active: true)

问题 3: 未订阅 message_created 事件

症状: webhook.subscriptions 不包含 'message_created'

解决:

webhook = Webhook.find(1)
webhook.update!(subscriptions: ['conversation_created', 'message_created', 'message_updated'])

问题 4: 代码修改未生效

症状: 代码已修改但行为未改变

解决: 重启服务器！

# 方法 1: overmind
overmind restart web

# 方法 2: 直接重启
# Ctrl+C 停止服务器
bundle exec rails server

问题 5: Webhook URL 无法访问

症状: 日志显示连接错误

解决:

1. 检查 URL 是否正确
2. 确认服务器可以从外网访问
3. 使用 webhook.site 测试

问题 6: content 过滤问题

症状: search_image 消息不触发 webhook

验证代码已正确修改:

# 检查 WebhookListener
File.read('app/listeners/webhook_listener.rb') =~ /search_image/
# 应该返回匹配结果

# 查看具体代码
puts File.read('app/listeners/webhook_listener.rb')[/def message_created.*?end/m]

应该看到：

def message_created(event)
  message = extract_message_and_account(event)[0]
  inbox = message.inbox

  return unless message.webhook_sendable?

  # For search_image type, allow webhook even if content is blank
  return if message.content.blank? && message.content_type != 'search_image'

  payload = message.webhook_data.merge(event: __method__.to_s)
  deliver_webhook_payloads(payload, inbox)
end

---

完整测试流程

步骤 1: 重启服务器

overmind restart web
# 或
bundle exec rails server

步骤 2: 确认 Webhook 配置

# Rails console
account = Account.find(2)
webhooks = account.webhooks

# 如果没有，创建一个
if webhooks.count == 0
  account.webhooks.create!(
    webhook_url: 'https://webhook.site/your-uuid',
    subscriptions: ['message_created'],
    active: true
  )
end

步骤 3: 发送测试消息

使用 curl:

curl -X POST "http://localhost:3000/api/v1/widget/messages?website_token=9n9D3JFHBorFTZLD7cQ49TMg&cw_conversation=xxx&locale=zh_CN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"content":"","content_type":"search_image","content_attributes":{"url":"https://test.jpg"}}}'

或在 /widget_tests 页面上传图片。

步骤 4: 立即检查日志

# 查看最新消息
message = Message.last
puts "content_type: #{message.content_type}"
puts "content: '#{message.content}'"

# 查看 webhook 日志
logs = Account.find(2).webhook_logs.order(created_at: :desc).limit(5)
logs.each { |log| puts "#{log.event_type} - #{log.status}" }

步骤 5: 检查 Webhook 接收

• 如果使用 webhook.site，刷新页面查看是否收到请求
• 查看请求内容是否包含 search_image 数据

---

调试命令汇总

# 1. 重启服务器
overmind restart web

# 2. 启动 Rails console
bundle exec rails c

# 3. 在 console 中依次执行:
load 'debug_webhook.rb'          # 全面诊断
load 'test_webhook_manual.rb'     # 手动触发测试

# 4. 发送测试消息
# (另开一个终端)
curl -X POST "http://localhost:3000/api/v1/widget/messages?..." \
  -H "Content-Type: application/json" \
  -d '{"message":{"content":"","content_type":"search_image","content_attributes":{"url":"https://test.jpg"}}}'

# 5. 检查结果 (在 Rails console 中)
Message.last
Account.find(2).webhook_logs.order(created_at: :desc).first

---

预期结果

成功的情况下，你应该看到：

1. ✅ 消息创建成功
2. ✅ Dashboard 显示消息
3. ✅ Webhook 日志有新记录 (status: 'success' 或 'failed')
4. ✅ Webhook 接收端收到请求

如果仍然不工作，请运行 debug_webhook.rb 并把输出发给我！