Using web-hooks

===============

Web-hooks are a notification system that could be compared to a callback.

Basically, pagure will make a HTTP POST request to one or more third party

server/application with information about what is or just happened.

Activating web-hooks notications

--------------------------------

To set-up a web-hook, simply go to the settings page of your project and

enter the URL to the server/endpoint that will receive the notifications.

If you wish to enter multiple URLs, enter one per line.

To stop all notifications, clear out that field.

Pagure will send a notification to this/these URL(s) for every action made

on this project: new issue, new pull-request, new comments, new commits...

.. note:: The notifications sent via web-hooks have the same payload as the

    notifications sent via `fedmsg <http: en="" latest="" www.fedmsg.com="">`_.</http:>

    Therefore, the list of pagure topics as well as example messages can be

    found in the `fedmsg documentation about pagure

    <https: en="" fedora-fedmsg.readthedocs.io="" latest="" topics.html#id550="">`_</https:>

Authenticating the notifications

--------------------------------

There is, in the settings page, a web-hook key which is used by the

server (here pagure) to sign the message sent and which you can use to

ensure the notifications received are coming from the right source.

Each POST request made contains some specific headers:

::

    X-Pagure

    X-Pagure-Project

    X-Pagure-Signature

    X-Pagure-Signature-256

    X-Pagure-Topic

``X-Pagure`` contains URL of the pagure instance sending this notification.

``X-Pagure-Project`` contains the name of the project on that pagure instance.

``X-Pagure-Signature`` contains the signature of the message allowing to

check that the message comes from pagure.

``X-Pagure-Signature-256`` contains the SHA-256 signature of the message

allowing to check that the message comes from pagure.

.. note:: These headers are present to allow you to verify that the webhook

        was actually sent by the correct Pagure instance. These are not

        included in the signed data.

``X-Pagure-Topic`` is a global header giving a clue about the type of action

that just occurred. For example ``issue.edit``.

.. warning:: The headers ``X-Pagure``, ``X-Pagure-Project`` and ``X-Pagure-Topic``

        are present for convenience only, they are not signed and therefore

        should not be trusted. Rely on the payload after checking the

        signature to make any decision.

Pagure relies on ``hmac`` to sign the content of its messages. If you want

to validate the message, in python, you can do something like the following:

::

    import hmac

    import hashlib

    payload =  # content you received in the POST request

    headers =  # headers of the POST request

    project_web_hook_key =  # private web-hook key of the project

    hashhex = hmac.new(

        str(project_web_hook_key), payload, hashlib.sha1).hexdigest()

    if hashhex != headers.get('X-Pagure-Signature'):

        raise Exception('Message received with an invalid signature')