Setting Up

Before anything else, you need to have a URL endpoint set up to receive POST requests. This will be a server location that you control and can use to process webhook messages as they are delivered.

Step 1

From the Settings > Webhooks page, click the “Add Endpoint” button.

Step 2

Enter your webhook receiver URL and select all event types you would like to be notified of from the list. As soon as the URL is saved, you will start to receive events at the URL specified; there is no further setup required. Please note that all URLs must start with “https” and have valid TLS encryption enabled.

Step 3

The Webhooks settings page shows your webhooks signing key. This value should be used on your website to authenticate that it is the gateway delivering these messages and not a third party.

Here is an example implementation in PHP:

  function webhookIsVerified($webhookBody, $signingKey, $nonce, $sig) {
    return $sig === hash_hmac("sha256", $nonce . "." . $webhookBody, $signingKey);
  }

  try {
    $signingKey = "YOUR_SIGNING_KEY_HERE";
    $webhookBody = file_get_contents("php://input");
    $headers = getallheaders();
    $sigHeader = $headers['Webhook-Signature'];

    if (!is_null($sigHeader) && strlen($sigHeader) < 1) {
    throw new Exception("invalid webhook - signature header missing");
  }

    if (preg_match('/t=(.*),s=(.*)/', $sigHeader, $matches)) {
    $nonce = $matches[1];
    $signature = $matches[2];
  } else {
    throw new Exception("unrecognized webhook signature format");
  }

    if (!webhookIsVerified($webhookBody, $signingKey, $nonce, $signature)) {
    throw new Exception("invalid webhook - invalid signature, cannot verify sender");
  }

    // webhook is now verified to have been sent by us, continue processing

    echo "webhook is verified";
    $webhook = json_decode($webhookBody);
    var_export($webhook);
  } catch (Exception $e) {
    echo "error: $e
";
  }

Step 4

Webhooks will only be delivered from the following IP addresses. It is advisable to limit your webhook endpoints to only receive requests originating from these addresses:

104.192.32.81 through 104.192.32.87

104.192.36.81 through 104.192.36.87