Real-Time Notifications (Webhooks)

You receive real-time notifications any time a charge changes state. The format of the notification is JSON and is the same as the Get Transaction API return.

Setup the Notification URL

There are two ways to specify the notification URL for a transaction:

Setup a global notification URL in your merchant account.
Send the notification URL when calling the API to create the transaction.

If you want to set up the global notification URL in your merchant account, please contact your account manager.

The notification URL provided via the API has higher priority. If you pass in a notification URL via the API, the notification is sent to it instead of the global URL set on your merchant account.

Validate the Notification

Retrieve the content of the callback.
Calculate the signature by creating an HMAC hash on the content and your notification key using SHA256 encoding.
Retrieve the X-callback-signature header.
Compare the signature from the header with your calculated signature.

Example in PHP


$input = file_get_contents('php://input');
$signature = hash_hmac('sha256', $input, $notificationKey);
$headers = apache_request_headers();
if (strcasecmp($signature, $headers['X-callback-signature']) == 0 )
{
  // Process the notification here
  http_response_code(200);
} else {
  http_response_code(403); // Invalid signature
}

Notification Retries

After successfully processing a notification, your endpoint must return an HTTP status of 200 OK to Cycle.

Whenever Cycle sends a notification, if you do not respond with a 200 OK, it assumes that you did not receive it, and the notification is placed in a queue. It will be resent periodically over the next 3 days until you either respond with a 200, or the time limit expires.

API Reference