assistant-storefront/WEBHOOK_TROUBLESHOOTING.md

# Webhook 不触发问题排查

## 快速检查步骤

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

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

```bash
# 如果使用 overmind
overmind restart web

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

### 2. 运行调试脚本

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

### 3. 检查 Webhook 配置

在 Rails console 中执行：

```ruby
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 测试

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

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

### 5. 查看 Webhook 日志

```ruby
# 最近的日志
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. 检查最近的消息

```ruby
# 查找 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`

**解决**:

```ruby
# 创建 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`

**解决**:

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

### 问题 3: 未订阅 message_created 事件

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

**解决**:

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

### 问题 4: 代码修改未生效

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

**解决**: 重启服务器！

```bash
# 方法 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

**验证代码已正确修改**:

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

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

应该看到：

```ruby
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: 重启服务器

```bash
overmind restart web
# 或
bundle exec rails server
```

### 步骤 2: 确认 Webhook 配置

```ruby
# 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:

```bash
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: 立即检查日志

```ruby
# 查看最新消息
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 数据

---

## 调试命令汇总

```bash
# 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` 并把输出发给我！