npm-hook

List all active hooks

$ npm hook ls

$ npm hook add [package_name] [event] [target_url]

$ npm hook rm [hook_id]

$ npm hook update [hook_id] [target_url]

npm hook add <pkg> <url> <secret> [--type=<type>]
npm hook ls [<pkg>]
npm hook update <id> <url> <secret>
npm hook rm <id>

pkg
    The name of the npm package for which to manage hooks. Used with add and ls.

url
    The target URL where the webhook payload will be sent. Used with add and update.

secret
    A secret string used to sign the webhook payload, enabling the receiver to verify the authenticity of the request. Used with add and update.

--type=
    Specifies the type of event the hook should respond to. Currently, `package` is the primary supported type, covering publish, unpublish, and dist-tag changes. Used with add.

id
    The unique identifier of an existing hook, obtained from npm hook ls. Used with update and rm.

--json
    Output data in JSON format. Applies to ls.

--registry=
    The registry URL to use for the command, overriding the default.

--loglevel=
    Set the logging level for output messages.

The `npm hook` command provides a mechanism for package maintainers to manage webhooks associated with their packages on the npm registry. These webhooks allow external services to be notified and react automatically when specific events occur related to a package, such as publish, unpublish, or dist-tag changes. By setting up webhooks, developers can integrate their npm package workflow with various external tools for purposes like continuous integration, deploying documentation, sending notifications, or updating other systems.

The command offers subcommands to add new hooks, ls (list) existing hooks for a package or globally, update an existing hook's details (like its URL or secret), and rm (remove) a hook. Each hook requires a target URL to send the payload to and a secret for signature verification, ensuring the authenticity of the incoming webhook requests. This feature is crucial for automating tasks and building responsive systems around package lifecycle events in the npm ecosystem.

Authentication Required: Users must be logged in to npm (npm login) and have appropriate permissions (ownership or maintainer status) for the target package to manage its hooks.
Security of Secrets: The secret provided for webhooks should be a strong, randomly generated string. It's crucial for verifying the authenticity of incoming webhook requests and should be stored securely.
Registry Specific: Hooks are managed specifically for the npm registry and are not generic system hooks.
Limited Scope: Currently, the primary event type supported is `package`, covering publish, unpublish, and dist-tag changes. Other event types might be limited or not directly exposed via the `add` command's --type option.
Rate Limits: While not strictly documented for `npm hook` itself, webhooks usually have associated rate limits or delivery guarantees set by the registry.

When a webhook is triggered, the npm registry sends an HTTP POST request to the configured URL. The request body contains a JSON payload with details about the event (e.g., package name, version, event type). The request also includes an `x-npm-signature` header, which is a HMAC-SHA256 signature calculated using the secret and the payload, allowing the receiver to verify the request's origin.

After adding a hook, it's recommended to test it by performing the triggering action (e.g., publishing a test package) or by sending a dummy payload to the webhook URL and checking the recipient service for logs. Services like `webhook.site` can be used to quickly inspect incoming webhook payloads.

The `npm hook` subcommand was introduced with npm version 5.7.0, released in early 2018. Its introduction marked a significant step towards enabling greater automation and integration capabilities for package maintainers within the npm ecosystem. Prior to this, programmatic reactions to package events typically required polling the npm registry or relying on external services that provided such functionality. The `hook` command provided a native, first-party solution for setting up real-time notifications, aligning npm with modern software development practices that emphasize continuous integration and automated workflows. It aimed to empower maintainers to build more sophisticated and responsive tooling around their package releases.

npm(1), npm login(1), npm publish(1), npm owner(1)