Blame doc/usage/using_webhooks.rst

Pierre-Yves Chibon b5fb9a
Using web-hooks
Pierre-Yves Chibon b5fb9a
===============
Pierre-Yves Chibon b5fb9a
Pierre-Yves Chibon b5fb9a
Web-hooks are a notification system that could be compared to a callback.
Pierre-Yves Chibon b5fb9a
Basically, pagure will make a HTTP POST request to one or more third party
Pierre-Yves Chibon b5fb9a
server/application with information about what is or just happened.
Pierre-Yves Chibon f694ba
Pierre-Yves Chibon 28bff3
Activating web-hooks notications
Pierre-Yves Chibon 28bff3
--------------------------------
Pierre-Yves Chibon 28bff3
Pierre-Yves Chibon f694ba
To set-up a web-hook, simply go to the settings page of your project and
Pierre-Yves Chibon 67f938
enter the URL to the server/endpoint that will receive the notifications.
Pierre-Yves Chibon 28bff3
If you wish to enter multiple URLs, enter one per line.
Pierre-Yves Chibon 28bff3
To stop all notifications, clear out that field.
Pierre-Yves Chibon 28bff3
Pierre-Yves Chibon 28bff3
Pagure will send a notification to this/these URL(s) for every action made
Pierre-Yves Chibon 28bff3
on this project: new issue, new pull-request, new comments, new commits...
Pierre-Yves Chibon 28bff3
Pierre-Yves Chibon 28bff3
.. note:: The notifications sent via web-hooks have the same payload as the
Pierre-Yves Chibon 28bff3
    notifications sent via `fedmsg <http: en="" latest="" www.fedmsg.com="">`_.</http:>
Pierre-Yves Chibon 28bff3
    Therefore, the list of pagure topics as well as example messages can be
Pierre-Yves Chibon 28bff3
    found in the `fedmsg documentation about pagure
Pierre-Yves Chibon 28bff3
    <https: en="" fedora-fedmsg.readthedocs.io="" latest="" topics.html#id550="">`_</https:>
Pierre-Yves Chibon 28bff3
Pierre-Yves Chibon 28bff3
Authenticating the notifications
Pierre-Yves Chibon 28bff3
--------------------------------
Pierre-Yves Chibon f694ba
Pierre-Yves Chibon 67f938
There is, in the settings page, a web-hook key which is used by the
Pierre-Yves Chibon 67f938
server (here pagure) to sign the message sent and which you can use to
Pierre-Yves Chibon 67f938
ensure the notifications received are coming from the right source.
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon d28610
Each POST request made contains some specific headers:
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon 414e87
::
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon d28610
    X-Pagure
Pierre-Yves Chibon d28610
    X-Pagure-Project
Pierre-Yves Chibon 414e87
    X-Pagure-Signature
Patrick Uiterwijk e99b9a
    X-Pagure-Signature-256
Pierre-Yves Chibon d28610
    X-Pagure-Topic
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon d28610
``X-Pagure`` contains URL of the pagure instance sending this notification.
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon d28610
``X-Pagure-Project`` contains the name of the project on that pagure instance.
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon 414e87
``X-Pagure-Signature`` contains the signature of the message allowing to
Pierre-Yves Chibon 414e87
check that the message comes from pagure.
Pierre-Yves Chibon 72c25a
Patrick Uiterwijk e99b9a
``X-Pagure-Signature-256`` contains the SHA-256 signature of the message
Patrick Uiterwijk e99b9a
allowing to check that the message comes from pagure.
Patrick Uiterwijk e99b9a
Patrick Uiterwijk 213059
.. note:: These headers are present to allow you to verify that the webhook
Patrick Uiterwijk 213059
        was actually sent by the correct Pagure instance. These are not
Patrick Uiterwijk 213059
        included in the signed data.
Patrick Uiterwijk 213059
Pierre-Yves Chibon d28610
``X-Pagure-Topic`` is a global header giving a clue about the type of action
Pierre-Yves Chibon d28610
that just occurred. For example ``issue.edit``.
Pierre-Yves Chibon d28610
Pierre-Yves Chibon d28610
.. warning:: The headers ``X-Pagure``, ``X-Pagure-Project`` and ``X-Pagure-Topic``
Pierre-Yves Chibon d28610
        are present for convenience only, they are not signed and therefore
Pierre-Yves Chibon d28610
        should not be trusted. Rely on the payload after checking the
Pierre-Yves Chibon d28610
        signature to make any decision.
Pierre-Yves Chibon d28610
Pierre-Yves Chibon 72c25a
Pagure relies on ``hmac`` to sign the content of its messages. If you want
Pierre-Yves Chibon ed2aeb
to validate the message, in python, you can do something like the following:
Pierre-Yves Chibon 72c25a
Pierre-Yves Chibon 72c25a
::
Pierre-Yves Chibon 72c25a
Pierre-Yves Chibon 72c25a
    import hmac
Pierre-Yves Chibon 010886
    import hashlib
Pierre-Yves Chibon 72c25a
Pierre-Yves Chibon 72c25a
    payload =  # content you received in the POST request
Pierre-Yves Chibon 72c25a
    headers =  # headers of the POST request
Pierre-Yves Chibon 72c25a
    project_web_hook_key =  # private web-hook key of the project
Pierre-Yves Chibon 72c25a
Pierre-Yves Chibon 72c25a
    hashhex = hmac.new(
Pierre-Yves Chibon 72c25a
        str(project_web_hook_key), payload, hashlib.sha1).hexdigest()
Pierre-Yves Chibon 72c25a
Pierre-Yves Chibon 72c25a
    if hashhex != headers.get('X-Pagure-Signature'):
Pierre-Yves Chibon 72c25a
        raise Exception('Message received with an invalid signature')