{"id":28399806,"url":"https://github.com/gbuesing/hookforward","last_synced_at":"2025-07-29T00:38:18.037Z","repository":{"id":5845071,"uuid":"7061514","full_name":"gbuesing/hookforward","owner":"gbuesing","description":"Forward webhooks to your development app with CouchDB and NodeJS","archived":false,"fork":false,"pushed_at":"2013-07-18T21:59:53.000Z","size":176,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-28T02:39:18.751Z","etag":null,"topics":["couchdb","javascript","local-machine","webhook"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbuesing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-12-07T23:10:19.000Z","updated_at":"2022-02-01T19:10:59.000Z","dependencies_parsed_at":"2022-08-25T03:41:09.517Z","dependency_job_id":null,"html_url":"https://github.com/gbuesing/hookforward","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gbuesing/hookforward","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbuesing%2Fhookforward","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbuesing%2Fhookforward/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbuesing%2Fhookforward/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbuesing%2Fhookforward/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbuesing","download_url":"https://codeload.github.com/gbuesing/hookforward/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbuesing%2Fhookforward/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267610605,"owners_count":24115442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["couchdb","javascript","local-machine","webhook"],"created_at":"2025-06-01T08:10:59.944Z","updated_at":"2025-07-29T00:38:18.008Z","avatar_url":"https://github.com/gbuesing.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Hookforward\n===========\nHookforward 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.\n\nYou 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.\n\nI've used this setup to develop apps that receive [Stripe](https://stripe.com/) and [Transloadit](https://transloadit.com/) webhooks. Nice to be able to run an app on my local machine and have the whole moustrap work.\n\nThis is an alternative to using a service like [Localtunnel](http://progrium.com/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.\n\n\nInstall\n-------\n```\nnpm install -g hookforward\n```\n\n\nPer-project setup\n-----------------\n\n1. Get a publicly accessible CouchDB server (free plans available from [Cloudant](https://cloudant.com/) and [IrisCouch](http://www.iriscouch.com/))\n\n2. Create a database to store webhooks in, and optionally secure this DB with a username:pass.\n\n3. Run the ```hookforward push``` command with the url for the DB created in step 2, e.g.:\n```\nhookforward push https://user:pass@myname.cloudant.com/hooks\n```\nThis will push a design doc with an update function which stores HTTP POST requests as documents.\n\n4. Step 3 will output the hook capture url for your DB, which will look something like this:\n```\nhttps://user:pass@myname.cloudant.com/hooks/_design/hookforward/_update/capture\n```\nYou'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.)\n\n\nStarting the forwarder app\n--------------------------\n\nStart 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.:\n```\nhookforward start https://user:pass@myname.cloudant.com/hooks http://localhost:4567/myhandler\n```\n\nFor 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.\n\n\nTesting the setup\n-----------------\nWith the DB setup and the forwarder app started, the mousetrap is ready.\n\nMost 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:\n```\ncurl -X POST -d 'foo=bar' https://user:pass@myname.cloudant.com/hooks/_design/hookforward/_update/capture\n```\n\nThe 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.\n\nIf all is set up correctly, you should see a record of this webhook being received in your app's log.\n\n\nSpecifying different app endpoints per request\n----------------------------------------------\nIf 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.\n\nFor 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):\n```\nhttps://user:pass@myname.cloudant.com/hooks/_design/hookforward/_update/capture?notify_url=http%3A%2F%2Flocalhost%3A4567%2Fmyhandler/someid\n```\n\n\n.hookforwardrc\n--------------\nYou can create a .hookforwardrc file in the root of your project with your DB and notify urls:\n\n```\n{\n  \"db_url\": \"https://user:pass@myname.cloudant.com/hooks\",\n  \"notify_url\": \"http://localhost:4567/myhandler\"\n}\n```\n\nThis will allow you to run the hookforward executable without having to specify urls.\n\n\nLimitations\n-----------\nThis setup won't work for webhooks that contain binary data -- CouchDB will only accept binary data if it's encoded as Base64.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbuesing%2Fhookforward","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbuesing%2Fhookforward","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbuesing%2Fhookforward/lists"}