OpenClaw BlueBubbles Webhook 404 Bug Report

Summary

BlueBubbles webhook route returns 404 Not Found despite plugin logging "listening on /bluebubbles-webhook". Webhook requests from BlueBubbles server fail with 404 error.

Environment

• OpenClaw Version: 2026.3.13 (61d171a)
• OS: macOS 26.3.1 (arm64)
• Node.js: v22.22.1
• BlueBubbles Server: 1.9.9
• Installation Method: npm (stable channel)
• Network: Private LAN (IP addresses redacted)

Configuration

channels.bluebubbles

{
  "enabled": true,
  "serverUrl": "http://[REDACTED_IP]:1234",
  "password": "[REDACTED]",
  "webhookPath": "/bluebubbles-webhook",
  "dmPolicy": "pairing",
  "allowFrom": ["*"],
  "groupPolicy": "allowlist"
}

plugins.allow

["bluebubbles", "openclaw-qqbot"]

Steps to Reproduce

1. Configure BlueBubbles channel with webhookPath explicitly set
2. Enable plugins.allow to include "bluebubbles"
3. Restart OpenClaw gateway
4. Send test webhook request:

   curl -X POST "http://[REDACTED_IP]:18789/bluebubbles-webhook?password=[PASSWORD]" \
     -H "Content-Type: application/json" \
     -d '{"type":"new-message","text":"test"}'

5. Observe 404 Not Found response

Expected Behavior

Webhook request should return 200 OK and be processed by BlueBubbles plugin.

Actual Behavior

• HTTP 404 Not Found response
• BlueBubbles server logs show:

  [WebhookService] -> Status Text: Not Found
  [WebhookService] -> Error: Request failed with status code 404
  [WebhookService] Failed to dispatch "new-message" event to webhook
  

Logs

OpenClaw Gateway Logs

[default] starting provider (webhook=/bluebubbles-webhook)
[default] BlueBubbles webhook listening on /bluebubbles-webhook

Note: Plugin logs indicate webhook is listening, but HTTP requests return 404.

BlueBubbles Server Logs

[BlueBubblesServer] New Message from ***@me.com, "1"; Date: 3/16/2026, 12:10:06 AM
[WebhookService] Dispatching event to webhook: http://[REDACTED_IP]:18789/bluebubbles-webhook?password=***
[WebhookService] Failed to dispatch "new-message" event to webhook: http://[REDACTED_IP]:18789/bluebubbles-webhook?password=***
[WebhookService] -> Error: Request failed with status code 404
[WebhookService] -> Status Text: Not Found

Analysis

The issue appears to be a mismatch between:

1. Plugin layer: Successfully registers webhook route (logs "listening on /bluebubbles-webhook")
2. HTTP server layer: Does not expose the route (returns 404)

This suggests the registerPluginHttpRoute API is not properly wiring routes to the HTTP server in this configuration.

Related Issues

Based on CHANGELOG.md, similar issues have been fixed:

• fix(gateway): move plugin HTTP routes before Control UI SPA catch-all #31885: Gateway/Plugin HTTP route precedence
• fix(gateway): let POST requests pass through root-mounted Control UI to plugin handlers #31349: Gateway/Control UI basePath POST handling
• fix(gateway): let non-GET requests fall through controlUi routing when basePath is set #32311: Gateway/Control UI basePath webhook passthrough

However, this issue persists in 2026.3.13.

Workarounds Attempted

1. ✅ Explicitly set channels.bluebubbles.webhookPath
2. ✅ Configure plugins.allow to include "bluebubbles"
3. ✅ Restart OpenClaw gateway
4. ✅ Change dmPolicy to "open"
5. ✅ Set allowFrom to ["*"]

None resolved the 404 error.

Impact

• Cannot receive iMessage messages via BlueBubbles integration
• OpenClaw can send messages TO iMessage (outbound works)
• OpenClaw cannot receive messages FROM iMessage (inbound broken)

Additional Context

• BlueBubbles server is running correctly (responds to API calls)
• BlueBubbles detects new messages and attempts to send webhooks
• Other channels (QQ Bot) work correctly
• Gateway mode: local
• Gateway bind: lan

Reporter

• GitHub: (to be filled)
• Contact: via OpenClaw QQ Bot community

Labels: bug, bluebubbles, webhook, regression
Priority: High (breaks core functionality)