npm Hooks API

naftiko: 1.0.0-alpha2
info:
  label: npm Hooks API
  description: The npm Hooks API allows developers to subscribe to notifications about changes in the npm registry. Hooks
    send HTTP POST payloads to a configured URI whenever a package is changed, enabling developers to build integrations that
    respond to registry events in real time. Users can add hooks to follow specific packages, track all activity of given
    npm users, or monitor all packages within an organization or user scope. The API provides endpoints for creating, listing,
    updating, and deleting hook subscriptions. Note that npm hooks services have been deprecated as of July 2024.
  tags:
  - Npm
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: npm
    baseUri: https://registry.npmjs.org
    description: npm Hooks API HTTP API.
    authentication:
      type: bearer
      token: '{{NPM_TOKEN}}'
    resources:
    - name: npm-v1-hooks
      path: /-/npm/v1/hooks
      operations:
      - name: listhooks
        method: GET
        description: List webhooks
        inputParameters:
        - name: package
          in: query
          type: string
          description: Filter hooks by package name. Does not support regular expressions.
        - name: limit
          in: query
          type: integer
          description: Maximum number of hooks to return.
        - name: offset
          in: query
          type: integer
          description: Number of hooks to skip for pagination.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: npm-v1-hooks-hook
      path: /-/npm/v1/hooks/hook
      operations:
      - name: createhook
        method: POST
        description: Create a webhook
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: npm-v1-hooks-hook-id
      path: /-/npm/v1/hooks/hook/{id}
      operations:
      - name: gethook
        method: GET
        description: Get a webhook
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatehook
        method: PUT
        description: Update a webhook
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletehook
        method: DELETE
        description: Delete a webhook
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: npm-rest
    description: REST adapter for npm Hooks API.
    resources:
    - path: /-/npm/v1/hooks
      name: listhooks
      operations:
      - method: GET
        name: listhooks
        description: List webhooks
        call: npm.listhooks
        outputParameters:
        - type: object
          mapping: $.
    - path: /-/npm/v1/hooks/hook
      name: createhook
      operations:
      - method: POST
        name: createhook
        description: Create a webhook
        call: npm.createhook
        outputParameters:
        - type: object
          mapping: $.
    - path: /-/npm/v1/hooks/hook/{id}
      name: gethook
      operations:
      - method: GET
        name: gethook
        description: Get a webhook
        call: npm.gethook
        outputParameters:
        - type: object
          mapping: $.
    - path: /-/npm/v1/hooks/hook/{id}
      name: updatehook
      operations:
      - method: PUT
        name: updatehook
        description: Update a webhook
        call: npm.updatehook
        outputParameters:
        - type: object
          mapping: $.
    - path: /-/npm/v1/hooks/hook/{id}
      name: deletehook
      operations:
      - method: DELETE
        name: deletehook
        description: Delete a webhook
        call: npm.deletehook
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: npm-mcp
    transport: http
    description: MCP adapter for npm Hooks API for AI agent use.
    tools:
    - name: listhooks
      description: List webhooks
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: npm.listhooks
      with:
        package: tools.package
        limit: tools.limit
        offset: tools.offset
      inputParameters:
      - name: package
        type: string
        description: Filter hooks by package name. Does not support regular expressions.
      - name: limit
        type: integer
        description: Maximum number of hooks to return.
      - name: offset
        type: integer
        description: Number of hooks to skip for pagination.
      outputParameters:
      - type: object
        mapping: $.
    - name: createhook
      description: Create a webhook
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: npm.createhook
      outputParameters:
      - type: object
        mapping: $.
    - name: gethook
      description: Get a webhook
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: npm.gethook
      outputParameters:
      - type: object
        mapping: $.
    - name: updatehook
      description: Update a webhook
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: npm.updatehook
      outputParameters:
      - type: object
        mapping: $.
    - name: deletehook
      description: Delete a webhook
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: npm.deletehook
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    NPM_TOKEN: NPM_TOKEN