Package: thorn
Version:1.5.2Web:http://thorn.readthedocs.io/Download:http://pypi.python.org/pypi/thorn/Source:http://github.com/robinhood/thorn/Keywords:event driven, webhooks, callback, http, djangoTable of Contents:AboutWhat are webhooks?In useExampleWhat do I need?Quick StartAlternativesInstallationInstalling the stable versionDownloading and installing from sourceUsing the development versionGetting HelpMailing listIRCBug trackerContributingLicenseAboutThorn 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.SimpleAdd webhook capabilities to your database models using a single
decorator, including filtering for specific changes to the model.FlexibleAll Thorn components are pluggable, reusable and extendable.ScalableThorn can perform millions of HTTP requests every second by taking
advantage ofCeleryfor asynchronous processing.What are webhooks?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.In useNotable examples of webhooks in use are:SiteDocumentationGithubhttps://developer.github.com/webhooks/Stripehttps://stripe.com/docs/webhooksPayPalhttp://bit.ly/1TbDtvjExampleThis example adds four webhook events to the Article model of
an imaginary blog engine:from thorn import ModelEvent, webhook_model

@webhook_model   # <--- activate webhooks for this model
class Article(models.Model):
    uuid = models.UUIDField()
    title = models.CharField(max_length=100)
    body = models.TextField()

    class webhooks:
        on_create = ModelEvent('article.created')
        on_change = ModelEvent('article.changed'),
        on_delete = ModelEvent('article.removed'),
        on_publish = ModelEvent(
            'article.published',
            state__eq='PUBLISHED',
        ).dispatches_on_change(),

    @models.permalink
    def get_absolute_url(self):
        return 'article:detail', None, {'uuid': self.uuid}Users can now subscribe to the four events individually, or all of them
by subscribing toarticle.*, and will be notified every time
an article is created, changed, removed or published:$ curl -X POST                                                      \
> -H "Authorization: Bearer <secret login token>"                   \
> -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 theEvents Guidefor you to consult after reading
the quick start tutorial.What do I need?Version RequirementsThorn version 1.0 runs onPython (2.7, 3.4, 3.5)PyPy (5.1.1)Jython (2.7).Django (1.8, 1.9, 1.10)Django 1.9 adds thetransaction.on_commit()feature,
and Thorn takes advantage of this to send events only when
the transaction is committed.Thorn currently only supportsDjango, and an API for subscribing to events
is only provided forDjango REST Framework.Extending Thorn is simple so you can also contribute support
for your favorite frameworks.For dispatching web requests we recommend usingCelery, but you
can get started immediately by dispatching requests locally.UsingCeleryfor dispatching requests will require a message transport
likeRabbitMQorRedis.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.Quick StartGo immediately to thedjango-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.AlternativesThorn was inspired by multiple Python projects:dj-webhooksdjango-rest-hooksdurianInstallationInstalling the stable versionYou can install thorn either via the Python Package Index (PyPI)
or from source.To install usingpip,:$ pip install -U thornDownloading and installing from sourceDownload the latest version of thorn fromhttp://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 installThe last command must be executed as a privileged user if
you are not currently using a virtualenv.Using the development versionWith pipYou can install the latest snapshot of thorn using the following
pip command:$ pip install https://github.com/robinhood/thorn/zipball/master#egg=thornGetting HelpMailing listFor discussions about the usage, development, and future of Thorn,
please join thethorn-usersmailing list.IRCCome chat with us on IRC. The#thornchannel is located at theFreenodenetwork.Bug trackerIf you have any suggestions, bug reports or annoyances please report them
to our issue tracker athttps://github.com/robinhood/thorn/issues/ContributingDevelopment ofThornhappens at GitHub:https://github.com/robinhood/thornYou are highly encouraged to participate in the development
ofthorn. If you don’t like GitHub (for some reason) you’re welcome
to send regular patches.Be sure to also read theContributing to Thornsection in the
documentation.LicenseThis software is licensed under theNew BSD License. See theLICENSEfile in the top distribution directory for the full license text.