A simple docker base HTTP service based on Django that was built to catch and show webhook data in a testing environment. Includes a Django admin page what shows the url that was hit, and the data that was received.
THIS IS FOR DEVELOPMENT PURPOSES ONLY IT IS NOT RECOMMENDED FOR PRODUCTION USE
- A Postgres Database.
- Python 3.8+ or Docker (pinned at 3.12)
There are 2 ways to use this:
- Use the Docker image (easiest)
- Run this as a local Python service using the built-in Django server
The latest docker image is available at my docker hub. You can find it here
The image provides options to change the database settings via environment variables so that you can adjust to fit your system. The variables are:
DB_NAME
: The name of the database (e.g.,webhook_catcher
)DB_USER
: The username of the database (e.g.,postgres
)DB_PASS
: The password of the database (e.g.,postgres
)DB_HOST
: The host of the database (e.g.,127.0.0.1
)DB_PORT
: The port of the database (e.g.,5432
)
You can also change the default admin username and password as well. To do so simply pass in the
environment params of ADMIN_USER
and ADMIN_PASS
(defaults to admin
:admin
)
Other setting that can be adjusted are:
SECRET_KEY
Django's secret key value. See settings.py for default.DEBUG
: Django's debug setting (default: false).SKIP_CREATE_DB
Whentrue
(default: false) skips trying to automatically create the db if it's not there (this is useful for cloud deploys).
Included in the project is an example docker-compose.yml
that will bring up the project
with a postgres database and have it running on port 8181. You can then simply point your
webhooks to http://localhost:8181/
, and your browser to http://localhost:8181/admin/
to login
with the default admin to see what was captured.
You can of course run this locally using Django's built-in test server. Please don't forget to update parameters here with those of your system and choosing.
- Clone this repo.
- Create a local Python virtual environment and activate it (e.g.,
python -m venv ./.venv && source ./.venv/bin/activate
) - Install the requirements using pip (e.g.,
pip install -r requirements.txt
) - Create a file called
.env
in the project root (this file is git ignored FYI) - Copy this code block and replace it with the settings from your database setup:
DB_NAME=webhook_catcher DB_USER=postgres DB_PASS=postgres DB_HOST=127.0.0.1 DB_PORT=5432
- Run the Django migrations:
python manage.py migrate
- Run Django's static collection:
python manage.py collectstatic
- Run the
create_default_superuser
management command to create the admin user:python manage.py create_default_superuser --username="admin" --password="admin"
- Run the Django testserver:
python manage.py testserver 127.0.0.2:8181
to start the server. - Open your browser to
http://localhost:8181/admin/
and login to the admin.
Once you have the service up and running, it will support receiving data from any HTTP method on
any path (except those being with /admin/
or /static/
). The system will dump all data into a
TEXT
field and additionally attempts to store the incoming data that has the Content-Type
header of application/json
into a JSON field for easy viewing. It also will keep track of the
method used, the time the webhook was received, the incoming path, any query parameters as well as
any headers in the request. The service will always save the data no matter what and return a 204
response (no content) unless it fails to decode the json, in which case it will return a 400
instead with the error from the json decoder and the data only stored in the TEXT
field.
curl -X POST http://127.0.0.1:8181/foo/bar?process=webhook -H "Content-Type: application/json" -d "{\"test\":{\"data\": \"nested\"}}"
You can login to the Django Admin and see all the details of the call. The view of the data in the admin is read-only.
If you need help or find a bug or would like to ask for a feature (you could build it, see contributing below). Please first search to see if the issue exists on the github page. If not, please open a new ticket and explain in as much detail as possible how to recreate the issue or what feature you'd like to see.
This is an opensource project, contributions are welcome. Please follow the guidelines to contribute to this project.
- Use
pip
to install the additionaldev.requirements.txt
. - You may also find the
dev.docker-compose.yml
useful, which builds using the current directory and adds it as a volume so changes are reflected immediately.
Before submitting any code please be sure you have done the following:
- Run coding stands tools, these are isort, black and flake8. They should all pass.
- Run tox and check all tests have passed and that your code coverage is 95% or above.
Every bit of code you submit must be fully tested.
All testing is done using pytest, please follow pytest style testing (not unittest).
You can simply use tox to run the tests: tox -e py312
.