Webhook receiver mixin

wagtail_live.receivers.base.WebhookReceiverMixin

Mixin for receivers using the webhook technique.

Attributes:

Name	Type	Description
url_path	str	Path of the URL used by a messaging app to send new updates to this receiver.
url_name	str	Name of the URL for reversing/resolving.

get_urls() classmethod

Retrieves webhook urls after having ensured that a webhook connection is enabled with the corresponding messaging app.

Returns:

Type	Description
URLPattern	URL which messaging apps use to send new updates.

Exceptions:

Type	Description
WebhookSetupError	if the webhook connection with the messaging app didn't succeed.

Source code in wagtail_live/receivers/base.py

@classmethod
def get_urls(cls):
    """
    Retrieves webhook urls after having ensured that a webhook connection is enabled with
    the corresponding messaging app.

    Returns:
        URLPattern: URL which messaging apps use to send new updates.

    Raises:
        WebhookSetupError: if the webhook connection with the messaging app didn't succeed.
    """

    if not cls.webhook_connection_set():
        cls.set_webhook()

    return [
        path(cls.url_path, cls.as_view(), name=cls.url_name),
    ]

post(self, request, *args, **kwargs)

This is the main method for Webhook receivers.

It handles new updates from messaging apps in these three steps:

1. Verify the request.
2. Dispatch the new event and process the updates received.
3. Acknowledge the request.

Parameters:

Name	Type	Description	Default
request	HttpRequest	Http request	required

Returns:

Type	Description
HttpResponse	Forbidden if the request couldn't be verified. OK if the request is verified and updates have been succesfully processed.

Source code in wagtail_live/receivers/base.py

def post(self, request, *args, **kwargs):
    """
    This is the main method for Webhook receivers.

    It handles new updates from messaging apps in these three steps:

    1. Verify the request.
    2. Dispatch the new event and process the updates received.
    3. Acknowledge the request.

    Args:
        request (HttpRequest): Http request

    Returns:
        HttpResponse:
        - `Forbidden` if the request couldn't be verified.
        - `OK` if the request is verified and updates have been succesfully processed.
    """

    body = request.body.decode("utf-8")
    try:
        self.verify_request(request, body, *args, **kwargs)
    except RequestVerificationError:
        return HttpResponseForbidden("Request verification failed.")

    self.dispatch_event(event=json.loads(body))
    return HttpResponse("OK")

set_webhook() classmethod

Sets a webhook connection with the corresponding messaging app.

This method may be trivial for messaging apps which propose setting a webhook in their UI like Slack. It may also be the main method if we have to set up the webhook connection ourselves; like with Telegram for example.

Exceptions:

Type	Description
WebhookSetupError	if the webhook connection with the messaging app failed.

Source code in wagtail_live/receivers/base.py

@classmethod
def set_webhook(cls):
    """
    Sets a webhook connection with the corresponding messaging app.

    This method may be trivial for messaging apps which propose setting a webhook
    in their UI like Slack. It may also be the main method if we have to set up
    the webhook connection ourselves; like with Telegram for example.

    Raises:
        WebhookSetupError: if the webhook connection with the messaging app failed.
    """

    raise NotImplementedError

verify_request(self, request, body, *args, **kwargs)

Ensures that the incoming request comes from the messaging app expected.

Parameters:

Name	Type	Description	Default
request	HttpRequest	Http request	required
body	str	Body of the request	required

Exceptions:

Type	Description
RequestVerificationError	if the request verification failed

Source code in wagtail_live/receivers/base.py

def verify_request(self, request, body, *args, **kwargs):
    """
    Ensures that the incoming request comes from the messaging app expected.

    Args:
        request (HttpRequest): Http request
        body (str): Body of the request

    Raises:
        RequestVerificationError: if the request verification failed
    """

    raise NotImplementedError

webhook_connection_set() classmethod

Checks if webhook a connection is set.

We call this method before calling the set_webhook method in order to avoid sending unneccesary POST requests to the messaging app server.

Returns:

Type	Description
bool	True if a webhook connection is set, False else.

Source code in wagtail_live/receivers/base.py

@classmethod
def webhook_connection_set(cls):
    """
    Checks if webhook a connection is set.

    We call this method before calling the `set_webhook` method in order to
    avoid sending unneccesary POST requests to the messaging app server.

    Returns:
        bool:
        - `True` if a webhook connection is set,
        - `False` else.
    """

    raise NotImplementedError