codehook

Webhook logic and infrastructure automated
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

There are many ways to extend the capabilities of your favourite SaaS tools, and webhooks are my favourite. Webhooks are the foundation of modern API development. They enable us to react to changes in our systems, an incoming text message, a successful payment, or that latest pull request no matter our stack. 1

During my time in Stripe, I found that some users were confortable in getting a handler up and running in 30 minutes, others had to navigate weeks of company approvals to get the infrastructure to run one, and others simply did not know what to do. [2](user survey)

I think this tool will make webhooks easy for everyone, once and for all. Here's why:

• Your time should be focused on creating something amazing, and truly unique business logic. The infra to do it isn't unique
• You shouldn't be doing the same tasks over and over like creating a webhook boilerplate from scratch
• You should be able to run your code in your environments when you have control over then
• You shouldn't be blocked from running your code elsewhere if you want because of company buorocracy

Codehook aims to help you all of the above: an open source tool to help you build, test, deploy and host (optionally) webhook handlers 🚀

(back to top)

Built With

(back to top)

Getting Started

To get a local copy up and running follow these simple example steps.

Prerequisites

Codehook is a Python project that relies heavily on Typer and Boto3, with a few additional dependencies.

Installing Python is generally easy, and nowadays many Linux and UNIX distributions include a recent Python. If you do need to install Python and aren't confident about the task you can find a few notes on the BeginnersGuide/Download wiki page, but installation is unremarkable on most platforms.

Configuration

1. Get an AWS API Key at https://example.com
2. Get the API Key for your source system, such as Stripe.
3. Make sure to set the following environment variables:

  AWS_ACCESS_KEY_ID=
  AWS_SECRET_ACCESS_KEY=
  STRIPE_API_KEY=

(back to top)

Usage

The simplest case

Create a file named handler.py with the following content:

def handler_logic(body):
    return (200, "Hello, codehook!")

Run the codehook CLI

foo@bar:~$ codehook deploy --file handler.py

The end of the response will contain information about the endpoint:

Deployment complete 🚀
Function name: handler
API ID: 123456789
Webhook URL: https:/123456789.execute-api.us-east-1.amazonaws.com/prod/codehook
Webhook ID: we_abcdefghijkl

Make a POST request to the endpoint that was just created

foo@bar:~$ curl -X PUT https://123456789.execute-api.us-east-1.amazonaws.com/prod/codehook | json_pp

The body of your response should a tuple containing:

{
  "body" : "Handler logic skeleton",
  "status_code" : 200
}

Congratulations! You just deployed a live webhook endpoint 🎉

You can clean up by running

foo@bar:~$ codehook delete --all

A slightly more complex example

Your function handler receives a body parameter from the webhook event. For this example, create a file named echo.py with the following content:

def handler_logic(body):
    return (200, body)

Run the codehook CLI. You can specify a function name, and the source for the event. Currently codehook supports Stripe webhook events.

codehook deploy --file echo.py --name echo_function --source stripe --enabled-events '*'

Make a POST request to the endpoint that was just created, and pass a request body this time:

foo@bar:~$ curl -X PUT -H "Content-Type: application/json" -d '{"hello":"codehook"}' \
  https://123456789.execute-api.us-east-1.amazonaws.com/prod/codehook | json_pp

The body of your response this time should echo back what you sent:

{
  "body" : "{\"hello\":\"codehook\"}",
  "status_code" : 200
}

You can also delete your resources one by one by running

foo@bar:~$ codehook delete --lambda-function-name echo_function --api-id 123456789

For more examples, please refer to the Documentation

(back to top)

Roadmap

• Support for additional event sources
• Improve code generation capability
• Support for additional cloud providers

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please clone the repo, start a new branch, and create a pull request. You can also simply open an issue with the tag "enhancement". And don't forget to give the project a star!

1. Clone the Project

  git clone https://github.com/edujanicas/codehook.git

2. Create your Feature Branch

  git checkout -b feature/AmazingFeature

3. Install all the dependencies (Using poetry)

  poetry install

4. Copy .env.example into a .env file and fill in your API Keys

  cp .env.example .env

5. Run the CLI locally

  poetry run codehook [COMMAND]

6. Commit your Changes

  git commit -m 'Add some AmazingFeature'

7. Push to the Branch

  git push origin feature/AmazingFeature

8. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Eduardo Janicas - edujanicas@icloud.com

Project Link: https://github.com/edujanicas/codehook

(back to top)

Acknowledgments

• Soulfir

(back to top)