Configuring notifications for reclaims of transient virtual servers

Provisioning a transient virtual server instance

Transient virtual servers can be provisioned through the IBM Cloud console, IBM Cloud infrastructure customer portal, or through the SLDN API. For more information, see Provisioning transient instances.

Setting up the webhook

To set up the webhook, you need to assign the following parameters to the transient virtual server instance by using the SLDN API:

• URI - A valid HTTP URI to which the reclaim-scheduled notification is sent.
• Secret - A string that is used as the key to a hash algorithm to sign the request. Do not communicate the secret string to anyone else.

The webhook must be set up for each provisioned transient virtual server. However, the URI and the secret do not need to be unique.

Both parameters are required. If the URI or secret must be changed, call the method again with the new information.

The transient virtual server webhook can be set up through the SLDN API by using the following method:

SoftLayer_Virtual_Guest::setWebhook(uri, secret)

For more information, see the SLDN API method documentation for webhook set-up.

SoftLayer_Virtual_Guest::deleteWebhook()

Verifying the webhook requests

To verify reclaim-scheduled notifications, review the following items:

1. The timestamp of the request

   Check the time that the request was received against the timestamp in the request headers. If it is off by more than 30 seconds or so, do not accept the request. This action can help prevent replay attacks.

2. The nonce found in the request's "X-IBM-Nonce" header

   This value is a string that is randomly generated when the request is sent. You can choose to store previously received nonces to compare against the nonce included in the request. If the nonce in the request was used before, do not accept the request. This action can help prevent replay attacks.

3. Hash Message Authentication Code (HMAC) located in the request's "Authorization" header

   This value is a string that is hashed by using the HMAC-SHA256 algorithm that uses the provided secret string as the key, and then encoded into Base64. You need to construct the string, hash it, encode it to Base64, and then compare the result to the signature in the "Authorization" header. If they do not match, do not accept the request. See next section for details on creating the HMAC signature.

Anatomy of the reclaim-scheduled notification request payload

The request that is sent from the transient virtual server webhook is like any HTTP request in that it has headers and a payload. The payload is a JSON formatted string in the following form.

Key names might not be listed as shown in the example.

   {
      'event': 'reclaim-scheduled',
      'id': <string - that is the ID of the transient guest being reclaimed>,
      'link': <string - link for an API call to return info about the guest being reaped>,
      'serviceName': <string - name of the API service class>,
      'time stamp': <integer - timestamp of when the reclaim was scheduled>
   }

Code examples for creating the HMAC signature

Python:

# This assumes that the request headers are stored in a dictionary that are called headers and that the JSON
# content of the request was decoded into a dictionary called payload.

import base64
import hashlib
import hmac

secret = 'Your secret key'
canonical = 'POST' + headers['Content-Type'] + payload['id'] + payload['serviceName'] + payload['event'] \
	    + payload['timestamp'] + headers['X-IBM-Nonce']
signature = base64.b64encode(hmac.new(secret, canonical, hashlib.sha256).hexdigest())
match_flag = hmac.compare_digest(headers['Authorization'], signature)

PHP:

// This assumes that the request headers are stored in an associative array called $headers and that
// the JSON content of the request is decoded into an associative array called $payload.

$secret = 'Your secret key';
$canonical = 'POST' . $headers['Content-Type'] . $payload['id'] . $payload['serviceName'] . $payload['event']
	     . payload['time stamp'] . $headers['X-IBM-Nonce'];
$signature = base64_encode(hash_hmac('sha256', $canonical, $secret));
$matchFlag = hash_equals($headers['Authorization'], $signature);

Node.js:

// This assumes that the request headers are stored in variables that are named content_type, nonce, and auth_string.
// This also assumes that the content of the request is a JSON object called payload.

const crypto = require('crypto');

var canonical = 'POST' + content_type + payload.id + payload.serviceName + payload.event + payload.timestamp + nonce;
hmac = crypto.createHmac('sha256', secret).update(canonical);
signature = Buffer.from(hmac.digest('hex')).toString('base64');
matchFlag = crypto.timingSafeEqual(auth_string, signature);