Overview

This page describes the webhook feature and how to set it 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.

Each endpoint can be subscribed to specific events that happen in the gateway. Most events have multiple versions: success, failure, and unknown.

Available Event Types

Event Category	Description
Transactions	Sales, auths, captures, voids, refunds, and credits. Each transaction type can be filtered by successful, failed, and unknown transactions.
Check Status	NEW! Available for settled, returned, or late return check statuses.
Recurring	Available for new, updated, and/or canceled subscriptions and plans.
Settlement	Batch summaries and can be filtered by successful and failed settlements.
Chargebacks	If your processor supports chargeback reporting, chargebacks can be delivered as events.
Automatic Card Updater	Available for card records updated, marked as closed, or for customer contact in the Customer Vault and/or recurring subscription records.

Basic Structure

Field	Description
event_id	A unique identifier for this event.
event_type	The type of event that occurred.
event_body	The body of the event (depends on event type)

Where To Setup

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

How to Setup

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.

How to Validate

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:

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\n";
  }

IP Addresses

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