npm Hooks API

openapi: 3.1.0
info:
  title: 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.
  version: '1.0.0'
  contact:
    name: npm Support
    url: https://www.npmjs.com/support
  termsOfService: https://docs.npmjs.com/policies/terms
externalDocs:
  description: npm Hooks Documentation
  url: https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm
servers:
  - url: https://registry.npmjs.org
    description: npm Public Registry
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.
security:
  - bearerAuth: []
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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        npm access token provided as a Bearer token.
  parameters:
    hookId:
      name: id
      in: path
      description: >-
        The unique identifier of the webhook subscription.
      required: true
      schema:
        type: string
  schemas:
    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.
    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.
    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.
    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.