Table of Contents:



Used by the Celery dispatcher to decide how many HTTP requests each task will perform.

Default is 10.


Can be used to configure new webhook serializers, or modify existing serializers:

THORN_CODECS = {'application/json': serialize_json}


This setting enables you to add static event subscribers that are not stored in the database.

This is useful for e.g hardcoded webhooks between internal systems.

The value of this setting should be a mapping between event names and subscribers, where subscribers can be:

  • a URL or a list of URLs.
  • a dict configured subscriber supported by from_dict(), or a list of these.


    'user.on_create': '',
    'address.on_change': {
        'url': '',
        'content_type': 'application/x-www-form-urlencoded',
    'balance.negative': [

The value here can also be a callback function that returns more subscribers:

# can be generator, or just return list
def address_change_subscribers(event, sender=None, **kwargs):
    for url in subscribers_for('address.change'):
        yield url

    'address.on_change': [address_change_subscribers],


The dispatcher backend to use, can be one of the built-in aliases: “default”, “celery”, or “disabled”, or it can be the fully qualified path to a dispatcher backend class, e.g. “proj.dispatchers:Dispatcher”.

Default is “default”.


Optional configuration option to restrict the event destination choices for the Subscriber model.


Specify the path to a custom HMAC signing function, taking the arguments (digest_method, secret, message).

The recommended value for this setting is:


but for compatibility reasons the default is an HMAC signer using the itsdangerous library:


The compat version generates a signature that is difficult for users of non-Python languages to verify, so you’re highly discouraged form using the default signer.


List of permission classes to add to the Django Rest Framework views.


HTTP request timeout used as default when dispatching events, in seconds int/float.

Default is 3.0 seconds.


Enable/disable retry of HTTP requests that times out or returns an error respons.

Enabled by default.


Time in seconds (int/float) to wait between retries. Default is one minute.


Maximum number of retries before giving up. Default is 10.

Note that subscriptions are currently not cancelled if exceeding the maximum retry amount.


List of default validator functions to validate recipient URLs.

Individual events can override this using the recipient_validators argument.

The default set of validators will validate that:

  • That the IP address of the recipient is not on a local network.


    This only applies to IP addresses reserved for internal use, such as, and

    If you have private networks on a public IP address you can block them by using the block_cidr_network() validator.

  • The scheme of the recipient is either HTTP or HTTPS.

  • The port of the recipient is either 80, or 443.

This is expressed in configuration as:

    validators.ensure_protocol('http', 'https'),
    validators.ensure_port(80, 443),

More validators can be found in the API reference for the thorn.validators module.



New in version 1.5.

When enabled the webhook dispatch will be tied to any current database transaction: webhook is sent on transaction commit, and ignored if the transaction rolls back.


When using Django this requires Django versions 1.9 or above.


Specify a custom subscriber model as a fully qualified path. E.g. for Django the default is "thorn.django.models:Subscriber".