Skip to main content

wazo-webhookd

Overview​

wazo-webhookd is a component responsible for managing subscriptions to internal platform events, such that custom behavior can be triggered in reaction to those events. This can be used to allow components external to the Wazo Platform to be notified of those events, in effect allowing for asynchronous integrations with other systems.

A subscription is a resource managed through wazo-webhookd, which associates a list of internal events to some type of reaction mechanism which is to be triggered from those events.

Different types of subscriptions are supported, and one can extend the types of subscription supported (the mechanism by which the events will be processed) through Python plugins for the wazo-webhookd.services namespace (see below).

The types of subscription currently supported natively (in the core implementation of wazo-webhookd) are:

  • http subscriptions
  • mobile subscriptions

Mobile Subscriptions​

As well as supporting configuration of custom behaviors through HTTP subscriptions and custom Python plugins, wazo-webhookd can also automatically create and manage special subscriptions for mobile users. These mobile subscriptions can provide push notification services for Wazo Platform events relevant to mobile users, such as incoming calls, voicemails, missed calls, chat messages, etc.

When a mobile user logs in, authentication events generated by that login are handled by wazo-webhookd, which in turn creates a mobile subscription for that user. That subscription specifies the internal events which are relevant for push notifications to mobile users. When those events are emitted by the platform, the subscription triggers the "hook" code that generates the relevant push notifications, by interacting with the configured third-party push notification service providers APIs (e.g. FCM, APNS).

Note: those subscriptions can not be created manually through the REST API.

For more details on configuring and using push notifications, see the push notification page.

Custom plugin-based subscriptions​

How to add a new webhookd type (a.k.a service)​

Here is an example of a webhook type that does nothing. Actually, it is very busy and sleeps for N seconds :) You may of course change this behaviour for something more suited to your needs.

Files:

  • setup.py
  • example_service/plugin.py

setup.py:

from setuptools import setup
from setuptools import find_packages

setup(
    name='wazo-webhookd-service-example',
    version='1.0',
    packages=find_packages(),
    entry_points={
    'wazo_webhookd.services': [
            # * "example" is the name of the service.
            #   It will be used when creating a subscription.
            # * "example_service" is the name of the directory above,
            #   the one that contains plugin.py
            # * "plugin" is the name of the above file "plugin.py"
            # * "Service" is the name of the class shown below
            'example = example_service.plugin:Service',
        ]
    }
)

example_service/plugin.py:

import time

class Service:

    def load(self, dependencies):
        celery_app = dependencies['celery']

        @celery_app.task
        def example_callback(subscription, event):
            '''
            * "subscription" is the subscription dict, same as the one returned by the REST API.
              The service-specific options are available in the "config" key, e.g. for http: the
              url is in subscription['config']['url'].
            * "event" contains the Wazo event that triggered the webhook.
              "event" is of the form:
              {
                  "name": "user_created",
                  "origin_uuid": "the UUID of the Wazo server that sent the event",
                  "data": {
                    "id": 12,  # the ID of the user that was created
                  }
              }
            '''
            tired = subscription['config']['sleep_time']
            time.sleep(tired)

        self._callback = example_callback

    def callback(self):
        return self._callback

To install this Python plugin, run:

python setup.py install

Once installed, you may create subscriptions with the type example:

POST /subscriptions
{
  "name": "Example webhook",
  "service": "example",
  "config": {
    "time_sleep": 10
  },
  "events": ["user_created"],
}

How to trigger code on a bus event​

example_service/plugin.py:

class Service:

    def load(self, dependencies):
        ...
        bus_consumer = dependencies['bus_consumer']
        bus_consumer.subscribe_to_event_names(uuid=uuid.uuid4(),
                                              event_names=['user_created'],
                                              user_uuid=None,
                                              wazo_uuid=None,
                                              callback=self.on_user_created)

    def on_user_created(self, body, event):
        logger.debug('User %s has been created!', body['uuid'])

How to programmatically create a subscription​

example_service/plugin.py:

from wazo_webhookd.plugins.subscription.service import SubscriptionService

class Service:

    def load(self, dependencies):
        ...
        subscription_service = SubscriptionService(dependencies['config'])
        ...
        subscription = subscription_service.create({
            'name': 'my-subscription',
            'service': 'http',
            'events': ['call_created'],
            'config': {
                'method': 'get',
                'url': 'https://me.example.com',
            },
        })