Security

Once your webhook is configured you should spend some time securing it.

It can be easily done by :

  • activating HTTPS
  • using HTTP basic authentication
  • validating requests signatures

HTTPS

We recommend to use the HTTPS protocol for your webhooks.
This protocol allows to keep the communication between our servers and your webhook encrypted.

❗️

If you prefer to use the HTTP protocol, keep in mind that an attacker could be able to capture this traffic and extract some important data.

HTTP basic authentication

If you have set a username and password in your webhook configuration your webhook will receive requests with an Authorization header containing those credentials.

In order to secure your webhook you will have to validate those credentials for each incoming requests.

❗️

You should always discard a request with invalid credentials.
Basic authentication is only secured when used with HTTPS.

Request signature

Finally if you have set a private key in your webhook configuration you will be able to validate the incoming requests signatures.

Each request contains a X-Hub-Signature header that contains its signature.
This header represents the hexadecimal view of the SHA-1 signature computed using the HMAC algorithm of the request payload and the Date header.

Example :

import hashlib
import hmac


def generate_signature(private_key, request_body, date_header):
    """
    Args:
        private_key (str): webhook private key
        request_body (str): the HTTP request body
        date_header (str): the value of the 'Date' header of the request
    """
    buffer = "date=" + date_header + "\n" + payload
    return "sha1=" + hmac.new(private_key.encode(),
                              buffer.encode(),
                              hashlib.sha1).hexdigest()

❗️

If the signature you receive does not match the one you compute, then it means that someone altered the request and may be trying to hack your webhook.

You should always discard a request with a wrong signature.