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 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 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 414e87
Each POST request made contains two specific headers:
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon 414e87
::
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon 414e87
    X-Pagure-Topic
Pierre-Yves Chibon 414e87
    X-Pagure-Signature
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon 414e87
Pierre-Yves Chibon 414e87
``X-Pagure-Topic`` is a global header giving a clue about the type of action
Pierre-Yves Chibon 414e87
that just occured. For example ``issue.edit``.
Pierre-Yves Chibon 414e87
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
Pierre-Yves Chibon 70d707
.. warning:: These headers are present for convenience only, they are not
Pierre-Yves Chibon 70d707
        signed and therefore should not be trusted. Rely on the payload
Pierre-Yves Chibon 70d707
        after checking the signature to make any decision.
Pierre-Yves Chibon 72c25a
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')
Pierre-Yves Chibon d5f7e1
Pierre-Yves Chibon d5f7e1
Pierre-Yves Chibon d5f7e1
The notifications sent via web-hooks have the same payload as what is sent
Pierre-Yves Chibon d5f7e1
via `fedmsg <http: en="" latest="" www.fedmsg.com="">`_. Therefore, the list of</http:>
Pierre-Yves Chibon d5f7e1
pagure topics as well as example messages can be found in the
Pierre-Yves Chibon d5f7e1
`fedmsg documentation about pagure
Pierre-Yves Chibon d5f7e1
<https: en="" fedora-fedmsg.readthedocs.org="" latest="" topics.html#id532="">`_</https:>