Clustaar

The Clustaar Developer Hub

Welcome to the Clustaar developer hub. You'll find comprehensive guides and documentation to help you start working with Clustaar as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Build a Webhook with Python

In order to build your webhook faster, we provide a Python micro-framework to let you focus on your webhook functionalities.

Read Webhooks reference first!

Before following this guide, please ensure you have read the introduction of the Webhooks reference first. It will help you understand how it work.

Installation

You can install this framework like any other python packages using pip :

pip install clustaar.webhook

Example

Webhook activation in a step

Simply activate the use webhook toggle in the desired step:

Webhook code example

Here is a webhook that will trigger an handler function each times it receives a conversation.step_reached event.

from clustaar.webhook import Webhook, events
from clustaar.schemas.models import StepReachedResponse, ConversationSession

def handler(request, response, notification):
    session = ConversationSession(values={"name": "John"})
    return StepReachedResponse(actions=[], session=session)


app = Webhook()
app.on(events.CONVERSATION_STEP_REACHED, handler)

Routing

Event

Routing is achieved by specifying an event name to the on() method while configuring your webhook :

app.on(events.CONVERSATION_STEP_REACHED, handler)

Filters

If you want to add some condition to route events based on the request received you can use filters.

In this example, handler will receive the requests only when the event is of type events.CONVERSATION_STEP_REACHED and the value of the JSON key data.step.id equals "507f191e810c19729de860ea" :

from clustaar.webhook.filters import JSONKeyEquals
app.on(events.CONVERSATION_STEP_REACHED,
       handler,
       filters=JSONKeyEquals("data.step.id", "507f191e810c19729de860ea"))

JSONKeyEquals

Validates that a JSON key equals an expected value.

data = {
    "user": {
        "id": 1
    }
}
filter = JSONKeyEquals("user.id", 1)
assert filter(data)
data["user"]["id"] = 2
assert not filter(data)

JSONKeyIn

Validates that a key is present in a defined set of values.

data = {
    "user": {
        "id": 1
    }
}
filter = JSONKeyIn("user.id", [1, 2])
assert filter(data)
data["user"]["id"] = 2
assert filter(data)
data["user"]["id"] = 3
assert not filter(data)

JSONKeyExists

Validates that a JSON key is present.

data = {
    "user": {
        "id": 1
    }
}
filter = JSONKeyExists("user.id")
assert filter(data)
del data["user"]["id"]
assert not filter(data)

StepID

Validates that the data.step.id matches the expected id.

data = {
    "data": {
        "step": {
            "id": "507f191e810c19729de860ea"
        }
    }
}
filter = StepID("507f191e810c19729de860ea")
assert filter(data)
del data["data"]["step"]["id"]
assert not filter(data)

If you pass a list of step IDs to the StepID filter it will validate the the data.step.id is present in the list.

Security

Request signature

If you want to validate the signature of the requests sent by clustaar, you need to provide a private key.
This private key must be set in your bot's webhook configuration.

app = Webhook(private_key="XXXXXXXXXX")

Authentication

If you want to add some authentication to your application you can pass the HTTP basic authentication credentials that you defined in your webhook configuration.

app = Webhook(auth_username="XXXXXXXXXX", auth_password="YYYYYYYYY")