Webhooks

Webhooks facilitate automated, real-time communication between HPE GreenLake cloud services and an external server of your choosing. For example, a webhook could notify you when a new audit log is created, or when subscriptions are about to expire. A new audit log or a subscription set to expire are examples of Events.

When you register a webhook on HPE GreenLake, you provide a Webhook URL, and then subscribe to HPE GreenLake events. When the event happens (a new device added to your workspace), HPE GreenLake sends an HTTP request with a message in JSON format to the webhook URL that you defined. The message contains factual details about the event.

You can configure your server to act when the message is received.

Webhooks and APIs

HPE GreenLake provides APIs to manage workspaces programmatically. Webhooks and APIs are similar, but serve different purposes. A webhook pushes information to you when an event happens. With an API, you intermittently or regularly request information by making calls to an API endpoint. Whether a webhook or an API call is the best approach depends on your scenario.

• Webhooks —Use webhooks when:
  • You want close to real time communication.
  • The communication is one way from HPE GreenLake to your webhook URL.
  • The event type requires immediate response from your organization.
  • There is a need for third party integration.
• APIs —Use APIs when you must access and manipulate data or when your information request is sporadic or one time. API calls also allow you to create, update, and delete information.

Webhook verification

HPE GreenLake webhooks use a verification challenge process to ensure that webhook connections are legitimate and secure. HPE GreenLake secures webhook notifications through HMAC (Hash-based Message Authentication Code) with SHA-256, a cryptographic hashing algorithm.

Challenge request

After registering a webhook, a verification challenge is sent to the destination (the Webhook URL). The event type is hpe.greenlake.events.v1beta1.webhooks.verification. The challenge request includes a unique, random string generated by the server sent in the body as a payload.

  {
    "specversion" : "1.0",
    "type" : "hpe.greenlake.events.v1beta1.webhooks.verification",
    "source" : "https://global.api.greenlake.hpe.com/events",
    "id" : "C234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "datacontenttype" : "application/json",
    "data" : {
        "challengeRequest" : "<TOKEN>"
    }
  }

Challenge response

The destination must read the value from the challengeRequest field and create an HMAC SHA-256 hash, using the webhook secret as salt and the challengeRequest value as a string to hash. When successful, the destination responds with a JSON object with the format {"verification": "CREATED_HASH"}and a HTTP 200 OK status.

Retry attempts

There is a maximum of three authentication attempts allowed. While attempting to authenticate, the webhook state is in the pending status. If there is a failure to respond, the webhook goes into the critical state. The three retries are completed within a maximum of 10 seconds.

1. The first retry occurs two seconds after the initial failure.
2. The second retry is scheduled for three seconds after the first retry.
3. The third and final retry takes place five seconds after the second retry.

Validating signatures

When setting up a webhook, you provide a Webhook Secret and webhook notifications include an HMAC signature in the HTTP header HPE-Webhook-Signature. This signature is prefixed with sha256=, indicating the use of SHA-256 for signature generation. These signatures must be validated at the destination:

1. Extract the signature from the HPE-Webhook-Signature header, noting the sha256= prefix.
2. Generate an HMAC signature with SHA-256 signature using the received payload and the Webhook Secret.
3. Match the extracted signature with the generated one to confirm the integrity and authenticity of the message.
4. In the case of a signature mismatch, reject the request by responding with any HTTP status code other than 200, indicating an invalid or unauthenticated request. A signature mismatch implies tampering or spoofing.

Shared secret rotation

Rotating a webhook's shared secret periodically helps ensure webhook communications stay secure. You should rotate (in other words, change) if you suspect a shared secret was compromised. However, if you use only one shared secret and rotate the key, there might be downtime until webhook destinations verify that the signature is updated. HPE GreenLake allows you to enter two shared secrets to avoid this downtime. Having two shared secrets allows you to use the second secret for verification while rotating the first, thus enabling zero downtime rotation.

With two shared secrets added, HPE GreenLake sends the shared secrets as separate headers. For example:

"hpe-webhook-signature": "sha256=e4fc3767ff7ed4a011b51eecad17ede130ba880f31327d266c277c670019bec2",
"hpe-webhook-signature2": "sha256=d60cada56c3ab97869aa7c20ffa82765a1f3ad23bd8d3ae5a6efcd49e215daae",

Configure your webhook destination to match both, and consider it a success if one of them is correct.

Webhook states

Webhooks states indicate the status of the webhook. There are five webhook states.

Pending—The pending state is assigned when HPE GreenLake has sent a verification challenge to the webhook destination and is awaiting a successful response. This is the initial state after a webhook registration, and indicates that the verification process is in progress.

Active—After receiving a successful response to the verification challenge, the webhook enters the active state. This state indicates that the webhook is operational and capable of sending notifications to its destination.

Warning—The webhook enters the warning state after crossing a threshold of consecutive failures due to errors on the destination side. This state serves as an alert that the webhook is experiencing issues, although it is still processing events.

Critical—If the webhook destination continues to fail after multiple attempts while in the warning state, it transitions to critical. In this state, the system halts event processing for the affected webhook, requiring manual intervention from the user to resolve the underlying issues.

Disabled—This state indicates that the webhook was intentionally turned off. All processing and notification activities are stopped.

Webhook HTTPS status codes

HTTPS status codes are three-digit numbers that indicate the outcome of an API or webhook request. The codes provide information about whether the request was successful or unsuccessful (failure). For failed requests, the codes are accompanied by a message that suggest the likely source of the issue.

• 100—199—The request was received, but the process is still ongoing.
• 200—299—The API or webhook request was accepted and successful.
• 300—399—This range of codes suggests a redirection has happened. For example, the URL moved, and the response provides a new URL (301 Moved Permanently).
• 400—499—A client error response. Typically, this range of status codes suggest problems with the request, the data in the request, or invalid authentication or authorization. In most cases, you can change the request and resubmit. The responses in this range include information intended to help determine the cause of the error and how to fix it.
• 500—599—A service error. Status codes in this range indicate that the server or service was not able to execute due to, for example, a site outage.

Retries and failure modes

Any failure to deliver is logged as a failure.

• After the first failure, the webhook enters the warning state.
• If there are more than 20 failures in a 12 hour period, the webhook enters the critical state.
• If there are no new failures in 12 hours, the webhook returns to the active state.

Definitions of important HTTPS status codes

The following table lists common HTTPS status codes and a description of what the code means.

HTTPS status codes definitions:

Configure a webhook handler

To receive HPE GreenLake events, you must configure a webhook destination endpoint that can listen for, accept, and respond to events sent by HPE GreenLake.

Once you have created and tested your webhook destination, you can use the HPE GreenLake UI to register the webhook and subscribe to events. When the event you are subscribed to occurs, HPE GreenLake sends an HTTP request with data about the event to your webhook destination URL.

This tutorial steps you through an example process to configure a webhook destination endpoint.

Step 1—Create a webhook destination endpoint

A webhook destination endpoint is a valid HTTPS endpoint (HTTP endpoints are not supported) on your server with a URL.

• The server must be able to receive and respond to POST requests from HPE GreenLake.
• The destination server must use a publicly signed certificate.
• The URI path for the webhook destination is your choice.

Further, you should add an authentication scheme to your destination.

Step 2—Write code to respond to the verification challenge

Upon registering your webhook, HPE GreenLake sends a verification challenge to your webhook destination endpoint. You need to ensure that the webhook destination endpoint responds promptly to the verification challenge. The verification challenge occurs during the initial registration of a webhook, when a webhook is edited, and when a webhook is deleted.

• The webhook destination endpoint will receive a GET request from HPE GreenLake.
• The event type for the verification challenge is com.hpe.greenlake.events.v1beta1.webhooks.verification , and it includes "data" : {"challengeRequest" : "<TOKEN>"}} . The webhook destination must read the value <TOKEN> from challengeRequest and create an HMAC SHA-256 hash, using the webhook secret as salt and the challengeRequest value as a string to hash.
• When successful, the destination must respond with a JSON object with the format {'verification': 'CREATED_HASH'} and a HTTP 200 OK status. Ensure that your webhook destination returns a 200 success response promptly, and before initializing any code or additional logic that could cause a timeout. Responding too slowly or with a non-200 status transitions the webhook to a "state": "DISABLED" and "status": "WARNING" .
• A maximum of three attempts to successfully respond to the verification challenge is allowed.

Example of challenge request:

{
  "data": {
     "challengeRequest": "8cbecfea-d708-4706-bba3-669225084a10"
  },
  "datacontenttype": "application/json",
  "id": "9d2698f2-0dd4-4870-b026-7e18c755e121",
  "source": "//<region>.api.greenlake.hpe.com/<api-group>",
  "specversion": "1.0",
  "subject": "3009de2825f211ec8a84fedebcb4a754",
  "time": "2024-12-12T19:09:05Z",
  "type": "com.hpe.greenlake.events.v1beta1.webhooks.verification"
}

Your webhook destination must respond with something like the following:

{
  "verification": "CREATED_HASH"
}

Step 3—Configure the webhook destination to handle HPE GreenLake events

Validate signatures

HPE GreenLake uses HMAC (Hash-based Message Authentication Code) with SHA-256 to secure event messages.

Your webhook destination endpoint must be able to validate signatures.

• When registering a webhook, you create a secret key, "secret": "<example-secret-key>" . See registering a webhook for more information.
• HPE GreenLake events contain an HMAC signature in the HTTP header HPE-Webhook-Signature , prefixed with sha256= . The event payload is hashed using SHA-256 combined with your secret key.

Your webhook endpoint destination must:

1. Extract the HMAC signature.
2. Generate the expected signature using the payload and the secret key.
3. Compare the extracted signature with the generated signature. A match confirms the authenticity of the event message.

The following code samples demonstrate how to generate the HMAC SHA-256 hash.

import hmac
import hashlib
import json
def verify_challenge(body):
# Extract the challengeRequest value from the data
challenge_request = body.data.get("challengeRequest", "")

# Create the HMAC SHA-256 hash
secret = “YOUR_SECRET"
hmac_hash = hmac.new(
key=secret.encode('utf-8'),
msg=challenge_request.encode('utf-8'),
digestmod=hashlib.sha256
)

# Get the hexadecimal representation of the hash
hash_digest = hmac_hash.hexdigest()

# Return the verification response
return {"verification": hash_digest}

function verifyChallenge(body) {
// Extract the challenge request
const challengeRequest = body.data?.challengeRequest || "";
// Secret key
const secret = “YOUR_SECRET";

const crypto = require('crypto');
// Create HMAC SHA-256 hash
const hmac = crypto.createHmac('sha256', secret);
hmac.update(challengeRequest);
const hashDigest = hmac.digest('hex');
// Return verification response
return { verification: hashDigest };
}

Receive JSON formatted POST requests

HPE GreenLake events are sent to the webhook destination as POST requests. Ensure the webhook destination endpoint accepts POST requests with a JSON payload.

• Following the CloudEvents standard , HPE GreenLake event headers include "Content-Type: application/json" declaring the format of the data being sent. Your webhook destination must be able to accept and parse this JSON payload.
  • An event might also include "datacontenttype" : "application/json" , which defines the media format of the "data" type.
• To guard against possible duplicate events, consider logging the event IDs you have already processed and implement logic not to process events already processed.
• The webhook destination endpoint must respond to correctly delivered events with a 2xx status code.

Browse the event catalog to confirm the formatting and data returned for the events you are interested in. At a minimum, HPE GreenLake events return the "specversion", "id", "source", and "type". The "type" field provides information on the kind of event that happened, for example, that a resource was created, updated, or deleted.

curl -X POST <Your Webhook URI> \
-H "Content-Type: application/cloudevents+json" \
-d '{
 "specversion": "1.0",
 "type": "com.hpe.greenlake.data.v1.volumes.created",
 "source": "//<region>.api.greenlake.hpe.com/<api-group>",
 "id": "e8fc75c1-9ad5-432d-a858-499d9f279647",
'

More commonly, HPE GreenLake events include additional information like "time" and "data". The "data" is the event payload, containing further information about the occurrence. This is either a single JSON object or an array of JSON objects.

curl -X POST <Your Webhook URI> \
-H "Content-Type: application/cloudevents+json" \
-d '{
 "specversion": "1.0",
 "type": "com.hpe.greenlake.data.v1.volumes.created",
 "source": "//<region>.api.greenlake.hpe.com/<api-group>",
 "id": "e8fc75c1-9ad5-432d-a858-499d9f279647",
 "time": "2023-08-19T09:00:00Z",
 "data": {
  "message": "Hello, World!"
 }
 }'

Step 4—Test the webhook destination

Use cURL, Postman, or a similar tool to send a POST request to your webhook destination endpoint with a sample payload.

An example using cURL:

curl -X POST <Your Webhook URI> \
-H "Content-Type: application/cloudevents+json" \
-d '{
 "specversion": "1.0",
 "type": "com.hpe.greenlake.data.v1.volumes.created",
 "source": ""//<region>.api.greenlake.hpe.com/compute-ops",
 "id": "e8fc75c1-9ad5-432d-a858-499d9f279647",
 "time": "2023-08-19T09:00:00Z",
 "data": {
 "message": "Hello, World!"
 }
 }'

Use your server console to check that the webhook was received and processed correctly.

Step 5—Secure your webhook destination

Take steps to secure your webhook destination.

• Use HTTPS communication.
• Consider restricting the webhook destination to the IP address of HPE GreenLake.
• Validate the signature of incoming requests to ensure they are from HPE GreenLake.
• Implement rate limiting on your server.
• Take steps to prevent replay attacks.

Step 6—Implement logic to process the events

Write code to process the events to match your organization's use cases for the webhook. For example, you could log events to a database, update a project management tool, or notify someone in your organization.

Next steps

At this point, you have:

• Created your webhook destination endpoint and included logic to respond to the verification challenge.
• Configured your webhook destination to handle and parse HPE GreenLake events.
• Secured your webhook destination.
• Browsed the HPE GreenLake event catalog and developed use cases for the events.
• Implemented logic to process events.

Now, you can:

1. Register your webhook with HPE GreenLake. See how to use the HPE GreenLake UI to register your webhook .
2. After you have registered your webhook, subscribe to events using the HPE GreenLake UI .