Cloud Events

Overview

A Cloud Event is the data that customer's services receive in their callbackUrls from Webhooks, it follows the basic CloudEvents spec with a couple of enhancements. This document describes all the properties used in Cloud Events.

Format

Message is delivered in form of POST request to your specified callbackUrl.

• Headers
• Body

Message Acknowledgement

To ensure successful delivery of messages, your webhook receiver must respond with an HTTP status code of 200, 201, 202, or 204 within 5 seconds. Any other response will be treated as a delivery failure.

If these requirements are not met, the message will be retried up to five times using an exponential backoff strategy:

• Retry 1: 1 minute (minimum backoff)
• Retry 2: 2 minutes
• Retry 3: 4 minutes
• Retry 4: 8 minutes
• Retry 5: 10 minutes (capped at maximum backoff)

The total retry duration is 25 minutes, after which the message will be saved in the Event Journal with a status of "Failed."

Note: The retry logic and backoff settings are not configurable.

You can replay failed messages using the Event Journal in the External Events UI: https://<tenant-name>.hiiretail.com/external-events/event-journal

More here: Event Journal.

Cloud Event headers

header name	example value	mandatory	description
User-Agent	Hii-Event-Gun/1.0	yes	Value is fixed, and can be used to identify requests from EXE
Authorization	Authorization docs	yes	Description on each type of authorization can be found in authorization docs
X-Hii-Signature	HS256=65fd717df8dd1ae9c432cf0000cfda46e1143122fcfc8af944482f9771c2a9d7	no	Provided only if your webhook has a sharedKey. Signature verification.
Content-Type	application/json	yes	Always application/json
Correlation-Id	ec580d96-4d6c-4a68-9724-c01ffa95bda1	yes	Unique identifier for tracing requests throughout all Hii Retail services.

Cloud Event body

Cloud event body is always in JSON format and passed as HTTP POST body in request.

field name	type	example value	mandatory	description
id	String	3454257574594417	yes	Event identifier. It's taken from the original message, that was sent into the Event Source.
time	String	2021-11-16T08:02:57.043Z	yes	Event timestamp. It's taken from the original message, that was sent into the Event Source.
type	String	iam.role-changed.v1	yes	Event source Id, describes the event type and the contents of the message
data	String	eyJleGFtcGxlIjogNDJ9	yes	Original message's data, encoded encoded using format in dataencoding field.
dataencoding	String	base64	yes	Encoding format for data field
datacontenttype	String	application/json	yes	Content type of the decoded data.
specversion	String	1.0	yes	A version of the spec this message complies to. Always set to 1.0.
source	String	exe-dispatch.retailsvc.com	yes	From where the message was produced .Always set to exe-dispatch.retailsvc.com
meta	Object	{}	yes	Additional info about message
meta.deprecationNotice	Object	{"removedAfter": "2022-01-31"}	no	Depredation notice for this event source, that usually mens that event source will be disabled soon
meta.deprecationNotice.removedAfter	String	2022-01-31	no	Indicates date, when Event Source will be disabled/deleted
meta.deprecationNotice.message	String	IAM group Unassigned event source is deprecated	no	Additional message in free text format, might explain reason behind deprecation
meta.deprecationNotice.replacedWith	String	iam.role-changed.v2	no	If deprecated event source have replacement Event source, this field might indicate it.

Exposed Attributes

Additional attributes might be added to meta field based on the event source configuration (configurable by event publishers only).

You can see a current list of meta attributes on your webhook using Open API preview functionality on the webhook page in Hii Console (https://<tenant>.hiiretail.com/external-events/webhooks/<webhook-id>).

Authorization

Every Cloud Event is sent with Authorization header, which can contain:

• Google Service Account ID Token (JWT format)
• Basic Authorization so receiver can verify, the origin of the Cloud Event.

Signature verification

To verify a signature, you would need to create message signature yourself and compare signatures with original from headers.

Possible algorithms:

Algo	format	example	desctiption
HS256	algo=signature	HS256=65fd717df8dd1ae9c432cf0000cfda46e1143122fcfc8af944482f9771c2a9d7	Hmac with sha256 of data field from body

You can generate signature by following steps:

• get value from data field in body (DO NOT DECODE IT)
• sign it with your sharedKey using algo from signature prefix (Always HS256 for now).

Example code in node.js

import {createHmac} from 'crypto';

const sharedKey = '<secret>';
const signature = 'HS256=' + createHmac('sha256', sharedKey).update(data).digest('hex');