thorn.events
¶
User-defined webhook events.
-
class
thorn.events.
Event
(name, timeout=None, dispatcher=None, retry=None, retry_max=None, retry_delay=None, app=None, recipient_validators=None, subscribers=None, request_data=None, allow_keepalive=None, **kwargs)[source]¶ Webhook Event.
Parameters: name (str) – Name of this event. Namespaces can be dot-separated, and if so subscribers can glob-match based on the parts in the name, e.g.
"order.created"
.Keyword Arguments: - timeout (float) – Default request timeout for this event.
- retry (bool) – Enable/disable retries when dispatching this event fails Disabled by default.
- retry_max (int) – Max number of retries (3 by default).
- retry_delay (float) – Delay between retries (60 seconds by default).
- recipient_validators (Sequence) –
List of functions validating the recipient URL string. Functions must raise an error if the URL is blocked. Default is to only allow HTTP and HTTPS, with respective reserved ports 80 and 443, and to block internal IP networks, and can be changed using the
THORN_RECIPIENT_VALIDATORS
setting:recipient_validators=[ thorn.validators.block_internal_ips(), thorn.validators.ensure_protocol('http', 'https'), thorn.validators.ensure_port(80, 443), ]
- subscribers – Additional subscribers, as a list of URLs, subscriber model objects, or callback functions returning these
- request_data – Optional mapping of extra data to inject into event payloads,
- allow_keepalive – Flag to disable HTTP connection keepalive for this event only. Keepalive is enabled by default.
Warning
block_internal_ips()
will only test for reserved internal networks, and not private networks with a public IP address. You can block those usingblock_cidr_network
.-
allow_keepalive
= True¶
-
app
= None¶
-
dispatcher
¶
-
prepare_recipient_validators
(validators)[source]¶ Prepare recipient validator list (instance-wide).
Note
This value will be cached
Return v
-
recipient_validators
= None¶
-
send
(data, sender=None, on_success=None, on_error=None, timeout=None, on_timeout=None)[source]¶ Send event to all subscribers.
Parameters: data (Any) – Event payload (must be json serializable).
Keyword Arguments: - sender (Any) – Optional event sender, as a
User
instance. - context (Dict) – Extra context to pass to subscriber callbacks.
- timeout (float) – Specify custom HTTP request timeout
overriding the
THORN_EVENT_TIMEOUT
setting. - on_success (Callable) – Callback called for each HTTP request
if the request succeeds. Must take single
Request
argument. - on_timeout (Callable) – Callback called for each HTTP request
if the request times out. Takes two arguments:
a
Request
, and the time out exception instance. - on_error (Callable) – Callback called for each HTTP request
if the request fails. Takes two arguments:
a
Request
argument, and the error exception instance.
- sender (Any) – Optional event sender, as a
-
subscribers
¶
-
class
thorn.events.
ModelEvent
(name, *args, **kwargs)[source]¶ Event related to model changes.
This event type follows a specific payload format:
{"event": "(str)event_name", "ref": "(URL)model_location", "sender": "(User pk)optional_sender", "data": {"event specific data": "value"}}
Parameters: name (str) – Name of event.
Keyword Arguments: - reverse (Callable) – A function that takes a model instance and returns the canonical URL for that resource.
- sender_field (str) – Field used as a sender for events, e.g.
"account.user"
, will useinstance.account.user
. - signal_honors_transaction (bool) –
If 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.
- Default is True (taken from the
THORN_SIGNAL_HONORS_TRANSACTION
setting), but
requires Django 1.9 or greater. Earlier Django versions will execute the dispatch immediately.
New in version 1.5.
- propagate_errors (bool) –
If enabled errors will propagate up to the caller (even when called by signal).
Disabled by default.
New in version 1.5.
- signal_dispatcher (signal_dispatcher) – Custom signal_dispatcher used to connect this event to a model signal.
- $field__$op (Any) –
Optional filter arguments to filter the model instances to dispatch for. These keyword arguments can be defined just like the arguments to a Django query set, the only difference being that you have to specify an operator for every field: this means
last_name="jerry"
does not work, and you have to uselast_name__eq="jerry"
instead.See
Q
for more information.
See also
In addition the same arguments as
Event
is supported.-
send
(instance, data=None, sender=None, **kwargs)[source]¶ Send event for model
instance
.Keyword Arguments: data (Any) – Event specific data. See also
Event.send()
for more arguments supported.
-
signal_dispatcher
¶