paperclipai/paperclip · error

Webhook ingestion is not enabled

Error message

Webhook ingestion is not enabled

What it means

501/503-style guard on the public plugin webhook ingestion route. Fires when webhook ingestion is disabled at the instance/app level, so external webhook deliveries cannot be recorded or dispatched even though the route is intentionally unauthenticated.

Source

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

   * 2. The plugin declares the `webhooks.receive` capability
   * 3. The `endpointKey` matches a declared webhook in the manifest
   *
   * The delivery is recorded in the `plugin_webhook_deliveries` table and
   * dispatched to the worker via the `handleWebhook` RPC method.
   *
   * **Note:** This route does NOT require board authentication — webhook
   * endpoints must be publicly accessible for external callers. Signature
   * verification is the plugin's responsibility.
   *
   * Response: `{ deliveryId: string, status: string }`
   * Errors:
   * - 404 if plugin not found or endpointKey not declared
   * - 400 if plugin is not in ready state or lacks webhooks.receive capability
   * - 502 if the worker is unavailable or the RPC call fails
   */
  router.post("/plugins/:pluginId/webhooks/:endpointKey", async (req, res) => {
    if (!webhookDeps) {
      res.status(501).json({ error: "Webhook ingestion is not enabled" });
      return;
    }

    const { pluginId, endpointKey } = req.params;

    // Step 1: Resolve the plugin
    const plugin = await resolvePlugin(registry, pluginId);
    if (!plugin) {
      res.status(404).json({ error: "Plugin not found" });
      return;
    }

    // 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;

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Enable webhook ingestion for the company (webhooksEnabled / plugin webhook setting) before calling the webhook endpoint.
2. Confirm the webhook route is being called against the intended company and plugin instance.

When it happens

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

Common situations: Returned when an inbound webhook is received but webhook ingestion is disabled for the company or plugin instance.

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