paperclipai/paperclip · error

Plugin does not have the webhooks.receive capability

Error message

Plugin does not have the webhooks.receive capability

What it means

400 from the plugin webhook ingestion route. Fires when the plugin's manifest exists but its capabilities array lacks 'webhooks.receive' — the plugin never declared webhook reception, so deliveries are refused.

Source

Thrown at server/src/routes/plugins.ts:2724

    // Step 2: Validate the plugin is in 'ready' state
    if (plugin.status !== "ready") {
      res.status(400).json({
        error: `Plugin is not ready (current status: ${plugin.status})`,
      });
      return;
    }

    // Step 3: Validate the plugin has webhooks.receive capability
    const manifest = plugin.manifestJson;
    if (!manifest) {
      res.status(400).json({ error: "Plugin manifest is missing" });
      return;
    }

    const capabilities = manifest.capabilities ?? [];
    if (!capabilities.includes("webhooks.receive")) {
      res.status(400).json({
        error: "Plugin does not have the webhooks.receive capability",
      });
      return;
    }

    // Step 4: Validate the endpointKey exists in the manifest's webhook declarations
    const declaredWebhooks = manifest.webhooks ?? [];
    const webhookDecl = declaredWebhooks.find(
      (w) => w.endpointKey === endpointKey,
    );
    if (!webhookDecl) {
      res.status(404).json({
        error: `Webhook endpoint '${endpointKey}' is not declared by this plugin`,
      });
      return;
    }

    // Step 5: Extract request data

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Add the webhooks.receive capability to the plugin manifest capabilities and reinstall/upgrade the plugin.
2. Grant the required capability on the plugin instance if capabilities are approved per-install.

When it happens

Trigger: Thrown at server/src/routes/plugins.ts:2702 when the library encounters an invalid state.

Common situations: Returned when an inbound webhook targets a plugin that has not declared the webhooks.receive capability in its manifest.

AI-assisted analysis of paperclipai/paperclip@a7e689b3c3 (2026-08-18). Data as JSON: /api/errors/c3d7b5f2c7703ae6. Report an issue: GitHub.