Design document for webhook2fedmsg

This document will investigate the possibility to create a more general solution converting various webhooks to fedora messaging messages.

External services

External services webhook2fedmsg will communicate with.

  • Database

    Will be used to store data about FAS user and tokens they added. We can consider supporting multiple tokens for each service per user. For database it would be best to use existing PostreSQL instance we already host in Fedora infra.

  • Webhook services

    The application will listen for webhooks from supported services. For each service should be separate backend, so it’s easier to remove/add new services.

  • FAS

    We need to authenticate user against Fedora Account System. For authentication we can use flask-oidc or authlib if Flask is not a framework of choice.

Use cases

Use cases that need to be implemented by webhook2fedmsg.

  • User login

    User will be able to login through web interface using FAS account.

  • User can add token for service

    When logged in user can add token for any service known by webhook2fedmsg. We should support multiple tokens per service.

  • User can modify/remove existing tokens

    When logged in user should be able to modify/remove tokens for services he added earlier.

  • User can list already added tokens

    When logged in user should be able to see tokens he already added and for which service they are.

  • User can see the URL for webhook

    webhook2fedmsg should show on web interface URL that could be used to set up webhook on the service.

  • Listening for webhook POST requests

    The application will provide endpoint for incoming requests. Ideally one per service. The webhook needs to be set by user on webhook service page.

  • Validating webhook POST requests

    Every incoming request from webhook services will be validated against the token database and search if it is valid token for service. It will drop any invalid request.

  • Processing webhook POST requests

    Each message needs to be converted from webhook JSON to Fedora message. The webhook2fedmsg should provide Fedora messaging schema for topics emitted by it.

Endpoints

Endpoints that should be provided by webhook2fedmsg.

  • /

    Index page. User is able to login here.

  • /tokens

    Token management page shows most information relevant to user - URLs for webhook endpoints, management of tokens.

  • /login

    Login page user is automatically redirected to, if not authenticated.

  • /<service>

    Endpoint where webhook service should sent POST requests.

  • /api

    Endpoint for API requests. API will be a nice to have alternative to web GUI.