Webhooks

Webhooks facilitate automated, real-time communication between HPE GreenLake platform 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 platform 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.

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 to active. 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: