Introducing hooks: get notifications of npm registry and package changes as they happen

Today, we’re excited to announce a simple, powerful new way to track changes to the npm registry — and build your own amazing new developer tools: hooks.

What?

Hooks are notifications of npm registry events that you’ve subscribed to. Using hooks, you can build integrations that do something useful (or silly) in response to package changes on the registry.

Each time a package is changed, we’ll send an HTTP POST payload to the URI you’ve configured for your hook. You can add hooks to follow specific packages, to follow all the activity of given npm users, or to follow all the packages in an organization or user scope.

For example, you could watch all packages published in the @npm scope by setting up a hook for @npm. If you wanted to watch just lodash, you could set up a hook for lodash.

When?

If you have a paid individual or organizational npm account, you can start using hooks right now.

Each user may configure a total of 100 hooks, and how you use them is up to you: you can put all 100 on a single package, or scatter them across 100 different packages. If you use a hook to watch a scope, this counts as a single hook, regardless of how many packages are in the scope. You can watch any open source package on the npm registry, and any private package that you control (you’ll only receive hooks for packages you have permission to see).

How?

Create your first hook right now using the wombat cli tool.

First, install wombat the usual way: npm install -g wombat. Then, set up some hooks:

Watch the npm package: wombat hook add npm https://example.com/webhooks shared-secret-text

Watch the @slack organization for updates to their API clients: wombat hook add @slack https://example.com/webhooks but-sadly-not-very-secret

Watch the ever-prolific substack: wombat hook add --type=owner substack https://example.com/webhooks this-secret-is-very-shared

Look at all your hooks and when they were last triggered: wombat hook ls

Protip: Wombat has several other interesting commands. wombat --help will tell you all about them.

We’re also making public an API for working with hooks. Read the docs for details on how you can use the API to manage your hooks without using wombat.

Why?

You can use hooks to trigger integration testing, trigger a deploy, make an announcement in a chat channel, or trigger an update of your own packages.

To get you started, here are some of the things we’ve built while developing hooks for you:

• npm-hook-receiver: an example receiver that creates a restify server to listen for hook HTTP posts. Source code.

• npm-hook-slack: the world’s simplest Slackbot for reporting package events to Slack; built on npm-hook-receiver.

• captain-hook: a much more interesting Slackbot that lets you manage your webhooks as well as receive the posts.

• wombat: a CLI tool for inspecting and editing your hooks. This client exercises the full hooks API. Source code.

• ifttt-hook-translator: Code to receive a webhook and translate it to an IFTTT event, which you can then use to trigger anything else you can do on IFTTT.

• citgm-harness: This is a proof-of-concept of how node.js’s Canary in the Gold Mine suite might use hooks to drive its package tests. Specific package publications trigger continuous integration testing of a different project, which is one way to test that you haven’t broken your downstream dependents.

What do you think?

We’re releasing hooks as a beta, and where we take it from here is up to you. What do you think about it? Are there other events you’d like to watch? Is 100 hooks just right, too many, or not enough?

We’re really (really) (really) interested to see what you come up with. If you build something useful (or silly) using hooks, don’t be shy to drop us a line or poke us on Twitter.

What’s next?

This is the tip of an excitement iceberg — exciteberg, if you will — of cool new ways to use npm. Watch this space!

npm ♥ you!