assistant-storefront/TROUBLESHOOTING_WEBHOOK.md

Webhook 不触发的排查步骤

问题原因

Webhook 不触发通常有以下几种原因：

1. ❌ 没有配置 Webhook
2. ❌ Webhook 未启用（active: false）
3. ❌ 没有订阅 message_created 事件
4. ❌ Webhook URL 不正确或无法访问

---

检查步骤

方法 1: 运行检查脚本

cd /home/lxj/project/chatwoot-develop

# 启动 Rails console
bundle exec rails c

# 加载检查脚本
load 'check_webhook.rb'

方法 2: 在 Rails Console 中手动检查

bundle exec rails c

然后执行：

# 1. 检查 Account
account = Account.find(2)
puts account.name

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

# 3. 查看每个 Webhook 的配置
webhooks.each do |webhook|
  puts "ID: #{webhook.id}"
  puts "URL: #{webhook.webhook_url}"
  puts "启用: #{webhook.active}"
  puts "订阅: #{webhook.subscriptions.inspect}"
end

# 4. 检查最近的调用日志
logs = account.webhook_logs.order(created_at: :desc).limit(5)
logs.each do |log|
  puts "#{log.event_type} - #{log.status} - #{log.response_code}"
end

---

修复方法

场景 1: 没有配置 Webhook

account = Account.find(2)

# 创建 Webhook
webhook = account.webhooks.create!(
  webhook_url: 'https://your-domain.com/webhook',  # 替换为你的 URL
  subscriptions: ['conversation_created', 'message_created', 'message_updated'],
  active: true
)

puts "✅ Webhook 已创建 (ID: #{webhook.id})"

场景 2: Webhook 未启用

webhook = Webhook.find(1)  # 替换为实际的 ID
webhook.update!(active: true)
puts "✅ Webhook 已启用"

场景 3: 未订阅 message_created 事件

webhook = Webhook.find(1)  # 替换为实际的 ID

# 添加 message_created 订阅
current_subs = webhook.subscriptions
webhook.update!(subscriptions: current_subs + ['message_created'])

puts "✅ 已添加 message_created 订阅"

场景 4: Webhook URL 无法访问

# 更新为正确的 URL
webhook = Webhook.find(1)
webhook.update!(webhook_url: 'https://correct-url.com/webhook')
puts "✅ URL 已更新"

---

完整配置示例

# Account 2 的完整 Webhook 配置
account = Account.find(2)

# 删除旧的 webhooks（可选）
# account.webhooks.destroy_all

# 创建新的 Webhook
webhook = account.webhooks.create!(
  webhook_url: 'https://your-domain.com/chatwoot/webhook',
  subscriptions: [
    'conversation_created',
    'conversation_status_changed',
    'message_created',
    'message_updated',
    'message_deleted'
  ],
  active: true,
  retry_frequency: 3  # 失败重试次数
)

puts "✅ Webhook 配置完成"
puts "   ID: #{webhook.id}"
puts "   URL: #{webhook.webhook_url}"
puts "   订阅事件: #{webhook.subscriptions}"

---

验证 Webhook 是否工作

方法 1: 检查日志

# 查看最近的 Webhook 日志
logs = WebhookLog.order(created_at: :desc).limit(10)

logs.each do |log|
  puts "事件: #{log.event_type}"
  puts "状态: #{log.status}"
  puts "响应码: #{log.response_code}"
  puts "URL: #{log.webhook.webhook_url}"
  puts "错误: #{log.error_message}"
  puts "时间: #{log.created_at}"
  puts "---"
end

方法 2: 重新发送 Webhook

# 找到之前发送的消息
message = Message.find(455)

# 手动触发 webhook
WebhookService.new(message.account, message.conversation).trigger_webhook(message, 'message_created')

puts "✅ Webhook 已重新发送"

方法 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"}}}'

然后立即检查：

# 查看最新日志
WebhookLog.order(created_at: :desc).first

---

常见问题

Q: Dashboard 能看到消息，但 Webhook 不触发？

A: 检查以下几点：

1. Webhook 是否启用（active: true）
2. 是否订阅了 message_created 事件
3. Webhook URL 是否可访问
4. 查看是否有错误日志：WebhookLog.where(status: 'failed')

Q: 如何调试 Webhook 请求？

A: 使用工具接收 Webhook 请求，例如：

• https://webhook.site（免费的 Webhook 测试工具）
• ngrok（将本地服务器暴露到公网）

Q: Webhook 调用失败会重试吗？

A: 会。Chatwoot 会根据 retry_frequency 配置自动重试失败的 Webhook。

---

快速解决方案

如果你只想快速测试 Webhook，使用 Webhook.site：

1. 访问 https://webhook.site 获取一个临时 URL
2. 在 Rails console 中配置：

account = Account.find(2)
webhook = account.webhooks.create!(
  webhook_url: 'https://webhook.site/your-uuid',  # 替换为你的 UUID
  subscriptions: ['message_created'],
  active: true
)

3. 发送测试消息
4. 在 webhook.site 查看是否收到请求

---

下一步

运行检查脚本后，告诉我结果，我可以帮你修复具体的问题！