Easy Webhooks for Python
.. image:: http://thorn.readthedocs.io/en/latest/images/thornbanner.png
==========================
|build-status| |coverage| |license| |wheel| |pyversion| |pyimp|
:Version: 1.5.2 :Web: http://thorn.readthedocs.io/ :Download: http://pypi.python.org/pypi/thorn/ :Source: http://github.com/robinhood/thorn/ :Keywords: event driven, webhooks, callback, http, django
.. contents:: Table of Contents: :local:
Thorn is a webhook framework for Python, focusing on flexibility and ease of use, both when getting started and when maintaining a production system.
The goal is for webhooks to thrive on the web, by providing Python projects with an easy solution to implement them and keeping a repository of patterns evolved by the Python community.
Simple
Add webhook capabilities to your database models using a single decorator, including filtering for specific changes to the model.
Flexible
All Thorn components are pluggable, reusable and extendable.
Scalable
Thorn can perform millions of HTTP requests every second by taking advantage of
Celery_ for asynchronous processing.
.. _
Celery: http://celeryproject.org/
A webhook is a fancy name for an HTTP callback.
Users and other services can subscribe to events happening in your system by registering a URL to be called whenever the event occurs.
The canonical example would be GitHub where you can register URLs to be called whenever a new change is committed to your repository, a new bugtracker issue is created, someone publishes a comment, and so on.
Another example is communication between internal systems, traditionally dominated by complicated message consumer daemons, using webhooks is an elegant and REST friendly way to implement event driven systems, requiring only a web-server (and optimally a separate service to dispatch the HTTP callback requests).
Webhooks are also composable, so you can combine multiple HTTP callbacks to form complicated workflows, executed as events happen across multiple systems.
Notable examples of webhooks in use are:
+------------+---------------------------------------------------------------+ | Site | Documentation | +------------+---------------------------------------------------------------+ | Github | https://developer.github.com/webhooks/ | +------------+---------------------------------------------------------------+ | Stripe | https://stripe.com/docs/webhooks | +------------+---------------------------------------------------------------+ | PayPal | http://bit.ly/1TbDtvj | +------------+---------------------------------------------------------------+
This example adds four webhook events to the Article model of an imaginary blog engine:
::
from django.urls import reverse from thorn import ModelEvent, webhook_model@webhook_model #
Users can now subscribe to the four events individually, or all of them by subscribing to
article.*, and will be notified every time an article is created, changed, removed or published:::
$ curl -X POST \ > -H "Authorization: Bearer " \ > -H "Content-Type: application/json" \ > -d '{"event": "article.*", "url": "https://e.com/h/article?u=1"}' \ > http://example.com/hooks/The API is expressive, so may require you to learn more about the arguments to understand it fully. Luckily it's all described in the
Events Guide_ for you to consult after reading the quick start tutorial.What do I need?
.. sidebar:: Version Requirements :subtitle: Thorn version 1.0 runs on
- Python (2.7, 3.4, 3.5) - PyPy (5.1.1) - Jython (2.7).
transaction.on_commit()
feature,
and Thorn takes advantage of this to send events only when
the transaction is committed.
Thorn currently only supports
Django, and an API for subscribing to events is only provided for
Django REST Framework.
Extending Thorn is simple so you can also contribute support for your favorite frameworks.
For dispatching web requests we recommend using
Celery_, but you can get started immediately by dispatching requests locally.
Using
Celery_ for dispatching requests will require a message transport like
RabbitMQ_ or
Redis_.
You can also write custom dispatchers if you have an idea for efficient payload delivery, or just want to reuse a technology you already deploy in production.
.. _
Celery: http://celeryproject.org/ .. _
Django: http://djangoproject.com/ .. _
Django REST Framework: http://www.django-rest-framework.org .. _
RabbitMQ: http://rabbitmq.com .. _
Redis: http://redis.io
Go immediately to the
django-guideguide to get started using Thorn in your Django projects.
If you are using a different web framework, please consider contributing to the project by implementing a new environment type.
Thorn was inspired by multiple Python projects:
dj-webhooks_
django-rest-hooks_
durian_
.. _
dj-webhooks: https://github.com/pydanny/dj-webhooks .. _
django-rest-hooks: https://github.com/zapier/django-rest-hooks .. _
durian: https://github.com/ask/durian/
.. _
Events Guide: http://thorn.readthedocs.io/en/latest/userguide/events.html
.. _installation:
You can install thorn either via the Python Package Index (PyPI) or from source.
To install using
pip,:
::
$ pip install -U thorn
.. _installing-from-source:
Download the latest version of thorn from http://pypi.python.org/pypi/thorn/
You can install it by doing the following,:
::
$ tar xvfz thorn-0.0.0.tar.gz $ cd thorn-0.0.0 $ python setup.py build # python setup.py install
The last command must be executed as a privileged user if you are not currently using a virtualenv.
.. _installing-from-git:
With pip ~~~~~~~~
You can install the latest snapshot of thorn using the following pip command:
::
$ pip install https://github.com/robinhood/thorn/zipball/master#egg=thorn
.. _
Events Guide: http://thorn.readthedocs.io/en/latest/userguide/events.html
.. _getting-help:
.. _mailing-list:
For discussions about the usage, development, and future of Thorn, please join the
thorn-users_ mailing list.
.. _
thorn-users: https://groups.google.com/forum/#!forum/thorn-users
.. _irc-channel:
Come chat with us on IRC. The #thorn channel is located at the
Freenode_ network.
.. _
Freenode: http://freenode.net
.. _bug-tracker:
If you have any suggestions, bug reports or annoyances please report them to our issue tracker at https://github.com/robinhood/thorn/issues/
.. _contributing-short:
Development of
Thornhappens at GitHub: https://github.com/robinhood/thorn
You are highly encouraged to participate in the development of
thorn. If you don't like GitHub (for some reason) you're welcome to send regular patches.
Be sure to also read the
Contributing to Thorn_ section in the documentation.
.. _
Contributing to Thorn: http://thorn.readthedocs.io/en/latest.html
.. _license:
This software is licensed under the
New BSD License. See the
LICENSEfile in the top distribution directory for the full license text.
.. # vim: syntax=rst expandtab tabstop=4 shiftwidth=4 shiftround
.. _
Events Guide: http://thorn.readthedocs.io/en/latest/userguide/events.html
.. |build-status| image:: https://secure.travis-ci.org/robinhood/thorn.png?branch=master :alt: Build status :target: https://travis-ci.org/robinhood/thorn
.. |coverage| image:: https://codecov.io/github/robinhood/thorn/coverage.svg?branch=master :target: https://codecov.io/github/robinhood/thorn?branch=master
.. |license| image:: https://img.shields.io/pypi/l/thorn.svg :alt: BSD License :target: https://opensource.org/licenses/BSD-3-Clause
.. |wheel| image:: https://img.shields.io/pypi/wheel/thorn.svg :alt: Thorn can be installed via wheel :target: http://pypi.python.org/pypi/thorn/
.. |pyversion| image:: https://img.shields.io/pypi/pyversions/thorn.svg :alt: Supported Python versions. :target: http://pypi.python.org/pypi/thorn/
.. |pyimp| image:: https://img.shields.io/pypi/implementation/thorn.svg :alt: Support Python implementations. :target: http://pypi.python.org/pypi/thorn/
.. _
Events Guide: http://thorn.readthedocs.io/en/latest/userguide/events.html