Web Hook Guide

For the developer who want develop a web hook of this project.

Overview

Web hook allows you to build an tool which can subscribe the event of Albireo server. Once an event is triggered. Albireo server will send an HTTP POST event to your registered URL. Web hook can be useful to make some notification when an episode is downloaded and push the notification to user.

Events

There several events available. See Web Hook Events

How it works

A Web hook relies on several APIs and responds several events to work. To make thing simple, we explain the interaction of web hook and Albireo server by different scenarios.

Initial Scenarios.

When you setup an web hook, it is waiting for events. At this very point of time, Albireo server doesn't know the web hook and the web hook is either not allow to access any API. You need register the web hook (if you are not admin, contact admin to help you register your web hook).

When a web hook is registered, a keep alive event will be emitted to your configured URL, Web Hook should consume this event and save the web_hook_id to a persistent storage. and then respond this id as http response body.

After known the id of web hook, it should actively request the revive API to finish this procedure.

The whole scenario time sequence chart:

Normal Scenario

Once A web hook finished its initialization. Keep alive event will emitted to this web hook every 5 minute to make sure this web hook is working. a web hook must respond this event with its id as response body.

For all different events, always respond the web hook id. otherwise, the web hook will be identified as DEAD.

Error Handling

Whenever an error occurred, either by network issue or web hook crash, Albireo server will modify the web hook status as 2 HAS_ERROR and increment the consecutive_failure_count by 1. when consecutive_failure_count is reach 10. certain web hook will be identified DEAD.

To avoid be identified as DEAD. a web hook must revive from the error state.To deal with this situation, web hook need do following:

• Check the keep alive event status field, when it is 2 (HAS ERROR) means the last event is not properly responded.
• Make a request to Albireo server's revive API with all the token id in a list token_id_list.
• update local storage about token information using the revive API response.
• once the revive request finished, the status is reset to 1 (ALIVE) and consecutive_failure_count is reset to 0.

Create a web hook

Setup an http/https server.

You should create an application which start an http/https server with a domain or fixed IP address. After you've done develop. make it online and move to the next step

Register web hook

To register your web hook, you can contact the admin. If yourself is an admin, go to the admin panel. fill the new web hook dialog with the three key information about your web hook.

• name, this is the name of your web hook, it must be unique among the Albireo server.
• description, it is also required to tell the user what is the web hook supposed to do and what's the privacy policy. Note that this is only a plain text. html or markdown is not worked.
• url, this is your web hook access point, the Albireo server will send event to this url. it must respond correctly.
• shared_secret, can be any string, this will be used to generate signature.

**You also need select required permissions for your web hook. **

Tell your user to add a token for your web hook.

Give a token to your user, which is a identifier for your user in your web hook. and let them to add in their user center.

You can make this progress simple by send an url to your user, then the process will be finished by one click.

The url should be http(s)://<albireo server>/settings/user?token_id=<your token id>&web_hook_id=<your web hook id>