Git Product home page Git Product logo

hookforward's Introduction

Hookforward

Hookforward allows you to forward webhooks (a.k.a. "server notifications" or "postbacks") from an external provider to an app running on your local machine without having to expose ports.

You need a publicly accessible CouchDB server that your webhook provider can post to. On your local machine, you run a simple program that listens for new webhook docs in CouchDB and forwards them on to your app running locally.

I've used this setup to develop apps that receive Stripe and Transloadit webhooks. Nice to be able to run an app on my local machine and have the whole moustrap work.

This is an alternative to using a service like Localtunnel. Localtunnel works ok (via voodoo I don't understand), but because they recycle urls frequenly, my app was receiving webhooks from various oddball services that the url was previously used for. Creepy.

Install

npm install -g hookforward

Per-project setup

  1. Get a publicly accessible CouchDB server (free plans available from Cloudant and IrisCouch)

  2. Create a database to store webhooks in, and optionally secure this DB with a username:pass.

  3. Run the hookforward push command with the url for the DB created in step 2, e.g.:

hookforward push https://user:[email protected]/hooks

This will push a design doc with an update function which stores HTTP POST requests as documents.

  1. Step 3 will output the hook capture url for your DB, which will look something like this:
https://user:[email protected]/hooks/_design/hookforward/_update/capture

You'll need to configure your setup to post webhooks to this url. Depending upon the service, you'll either need to specify this in an admin management console (e.g. Stripe), or in a param with every API call (e.g. Transloadit's "notify_url" param.)

Starting the forwarder app

Start the forwarder app on your local machine with the hookforward start command, specifying the db url and the local url for your app's webhook handler, e.g.:

hookforward start https://user:[email protected]/hooks http://localhost:4567/myhandler

For convenience, you can specify these urls in a .hookforwardrc file, and then you can just run hookforward start without any urls on the command line -- see instructions below.

Testing the setup

With the DB setup and the forwarder app started, the mousetrap is ready.

Most services will have an easy way to push out a test webhook to your app. If you can't do that, you can just post a simple request to your capture url via curl:

curl -X POST -d 'foo=bar' https://user:[email protected]/hooks/_design/hookforward/_update/capture

The forwarder app is listening for new documents in the DB via Couch DB's changes feed. So once the hook is captured in your DB, the forwarder app will receive the new webhook document, and then post that back to your local app.

If all is set up correctly, you should see a record of this webhook being received in your app's log.

Specifying different app endpoints per request

If you're using a service where you pass in the notify_url per request (like Transloadit), you can also specify your local app endpoint per request, by appending a notify_url param.

For example, here's a url that will allow the provider to post to your CouchDB, with a notify_url param that the forwarder app will use (instead of a url specifcied on command line or in .hookforwardrc):

https://user:[email protected]/hooks/_design/hookforward/_update/capture?notify_url=http%3A%2F%2Flocalhost%3A4567%2Fmyhandler/someid

.hookforwardrc

You can create a .hookforwardrc file in the root of your project with your DB and notify urls:

{
  "db_url": "https://user:[email protected]/hooks",
  "notify_url": "http://localhost:4567/myhandler"
}

This will allow you to run the hookforward executable without having to specify urls.

Limitations

This setup won't work for webhooks that contain binary data -- CouchDB will only accept binary data if it's encoded as Base64.

hookforward's People

Contributors

gbuesing avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.