Hooks
#####

.. _HOOKS Signing a Request:

Verifying a Request
*******************

To make sure the webhook is sent by Stasis, we sign it with the HMAC algorithm.

To verify the webhook sender:

* Get a webhook ``X-Api-Sig`` header value and payload as it is, without any alteration or converting to JSON.
* Receive the HTTP webhook body in bytes.
* Calculate the digest with the raw webhook payload in bytes and ``sha512`` HMAC algorithm using a secret key(provided upon webhook creation).

.. code-block:: python

    hmac.new(b'secret', b'body', digestmod=hashlib.sha512).hexdigest()

* Compare the ``X-Api-Sig`` header value with the calculated digest.

Response Codes
**************

In case your server responds with any ``2XX`` HTTP code, notification is considered delivered.

Example of API
**************

.. raw:: html

   <embed src="webhook.html" style="width:100%; height: 50vw;">

.. _HOOKS Debug:

Debug
*****

.. code-block:: bash

    python -c 'import hmac, hashlib; print(hmac.new(b"your secret", b"your http body", digestmod=hashlib.sha512).hexdigest())'