npm Hooks API

openapi: 3.1.0
info:
  title: npm Downloads 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.
  version: 1.0.0
  contact:
    name: npm Support
    url: https://www.npmjs.com/support
  termsOfService: https://docs.npmjs.com/policies/terms
servers:
- url: https://registry.npmjs.org
  description: npm Public Registry
security:
- bearerAuth: []
tags:
- name: Hooks
  description: Webhook subscription management for npm registry events. Create, list, update, and delete hook subscriptions to receive notifications when packages, scopes, or user activities change.
paths:
  /-/npm/v1/hooks:
    get:
      operationId: listHooks
      summary: List webhooks
      description: Retrieves all webhook subscriptions for the authenticated user. Results can be filtered by package name and paginated using limit and offset parameters.
      tags:
      - Hooks
      parameters:
      - name: package
        in: query
        description: Filter hooks by package name. Does not support regular expressions.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of hooks to return.
        required: false
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        description: Number of hooks to skip for pagination.
        required: false
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: List of hooks retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    description: List of hook subscription objects.
                    items:
                      $ref: '#/components/schemas/Hook'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /-/npm/v1/hooks/hook:
    post:
      operationId: createHook
      summary: Create a webhook
      description: Creates a new webhook subscription. The hook will send HTTP POST payloads to the specified endpoint URI whenever the watched entity changes. Hooks can watch individual packages, all packages belonging to a scope, or all packages published by a specific npm user.
      tags:
      - Hooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookCreateRequest'
      responses:
        '201':
          description: Hook created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /-/npm/v1/hooks/hook/{id}:
    get:
      operationId: getHook
      summary: Get a webhook
      description: Retrieves a specific webhook subscription by its identifier.
      tags:
      - Hooks
      parameters:
      - $ref: '#/components/parameters/hookId'
      responses:
        '200':
          description: Hook retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Hook not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateHook
      summary: Update a webhook
      description: Updates an existing webhook subscription. The endpoint URI and shared secret can be modified. The response includes the full updated hook object.
      tags:
      - Hooks
      parameters:
      - $ref: '#/components/parameters/hookId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookUpdateRequest'
      responses:
        '200':
          description: Hook updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Hook not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteHook
      summary: Delete a webhook
      description: Deletes a webhook subscription. The response includes the hook object that was deleted.
      tags:
      - Hooks
      parameters:
      - $ref: '#/components/parameters/hookId'
      responses:
        '200':
          description: Hook deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Hook not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: An error response from the npm API.
      properties:
        error:
          type: string
          description: The error type or code.
        message:
          type: string
          description: A human-readable description of the error.
    HookUpdateRequest:
      type: object
      description: Request body for updating an existing webhook subscription.
      required:
      - endpoint
      - secret
      properties:
        endpoint:
          type: string
          format: uri
          description: The updated URI to receive webhook payloads.
        secret:
          type: string
          description: The updated shared secret for payload signing.
    HookCreateRequest:
      type: object
      description: Request body for creating a new webhook subscription.
      required:
      - type
      - name
      - endpoint
      - secret
      properties:
        type:
          type: string
          description: The type of entity to watch for changes.
          enum:
          - package
          - scope
          - owner
        name:
          type: string
          description: The name of the entity to watch. For packages, use the package name. For scopes, use the scope name (e.g., @myorg). For owners, use the npm username.
        endpoint:
          type: string
          format: uri
          description: The URI to receive webhook payloads via HTTP POST.
        secret:
          type: string
          description: A shared secret used to sign webhook payloads. The signature is included in the x-npm-signature header of each delivery.
    Hook:
      type: object
      description: A webhook subscription object that defines what registry events trigger notifications and where those notifications are sent.
      properties:
        id:
          type: string
          description: The unique identifier for this hook subscription.
        username:
          type: string
          description: The npm username of the hook owner.
        name:
          type: string
          description: The name of the entity being watched. For packages, this is the package name. For scopes, this is the scope name. For owners, this is the npm username.
        type:
          type: string
          description: The type of entity being watched.
          enum:
          - package
          - scope
          - owner
        endpoint:
          type: string
          format: uri
          description: The URI where webhook payloads will be sent via HTTP POST.
        last_delivery:
          type: object
          description: Information about the last delivery attempt.
          properties:
            id:
              type: string
              description: The identifier of the last delivery.
            timestamp:
              type: string
              format: date-time
              description: When the last delivery was attempted.
            status:
              type: integer
              description: The HTTP status code received from the endpoint.
        response_code:
          type: integer
          description: The HTTP response code from the last delivery attempt.
        status:
          type: string
          description: The current status of the hook subscription.
        created:
          type: string
          format: date-time
          description: When the hook was created.
        updated:
          type: string
          format: date-time
          description: When the hook was last updated.
  parameters:
    hookId:
      name: id
      in: path
      description: The unique identifier of the webhook subscription.
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: npm access token provided as a Bearer token.
externalDocs:
  description: npm Hooks Documentation
  url: https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm