Derivatives of InboundHttpService
Derivatives of InboundHttpService facilitates exposing RESTful endpoints coupled with certain predefined features in Content Integration Framework. As of release 12.1.2, Content Integration Framework allows exposing RESTful endpoints (webhooks) to receive & process content lifecycle events.
Object event interpreter service (Webhook)
com.hcl.unica.system.integration.service.object.event.ObjectEventInterpreterService
The
com.example.service.rest.ExampleEventInterpreterService
class in asset-integration-starter project is a quick starter implementation for an object event interpreter service. It extends fromObjectEventInterpreterService
class. Implementing an object event interpreter service by extending standard ObjectEventInterpreterService exposes a webhook which can be invoked by the respective content repository to send content lifecycle event notifications.The
ObjectEventInterpreterService
class has a type parameter T, which represents the type of request (post deserialization) received from the client of webhook. In case ofExampleEventInterpreterService
, request body is expected in String format. The type parameter T can be any valid Jackson or JAXB annotated class if JSON or XML is expected in the request body. Deserialization of JSON & JAXB happens based on theContent-Type
request header. Having said that, Content Integration Framework supports only application/json & text/xml or application/xml type of request body if automatic deserialization is desired.Object event interpreter service does not directly respond to the client. Instead, it helps to interpret the incoming event information and shares the necessary details with Content Integration Framework for further processing. Content Integration Framework responds to the client accordingly. It responds with 200 HTTP response if interpretation succeeds. If event interpreter service cannot understand the event and fails to figure out necessary details about the event, Content Integration Framework responds with appropriate 4xx HTTP error response.
ObjectEventInterpreterService
class mandates the event interpreter service to implement following methods:ObjectEventListenerRequestSpec getRequestSpec(ServiceConfig serviceConfig)
This method accepts an object of
ServiceConfig
class and returns an object of typeObjectEventListenerRequestSpec
. TheObjectEventListenerRequestSpec
is essentially the partial specification of webhook’s signature. TheObjectEventListenerRequestSpec
wraps an object ofInboundHttpRequestSpec
, which comprises the relative endpoint URL of the webhook, and the HTTP methods supported by the webhook being exposed. The relative URL can contain path variables enclosed in curly braces. Refer to thegetRequestSpec
implementation inExampleEventInterpreterService
. Runtime values for these path variables can be obtained fromInboundHttpRequestContext
. See InoundHttpRequestContext<T> section for more details.Avoiding webhook conflicts
If plugin implements more than one event interpreter services, then it is important to note that no two interpreter services should expose webhooks with conflicting signatures. For example, if one interpreter service exposes a webhook with relative URL as /wh/{contentId}, supporting POST method, then another interpreter service must use different relative URL and/or different HTTP method to form a different signature. Thus, another webhook for supporting PUT method for the same relative URL /wh/{contentId} would be completely valid. (Note that single interpreter service can support multiple HTTP methods for same relative URL.)
Optional<ObjectEventDetails> interpret(InboundHttpRequestContext<T> executionContext)
This method accepts an object of InboundHttpRequestContext<T>, wherein T represents the type of request body. As explained in InoundHttpRequestContext<T> section section,
InboundHttpRequestContext
can be used to obtain contextual information, including request payload, path variables, request parameters & request headers. In response, it is expected to return an object ofObjectEventDetails
comprising the details of the event received via exposed webhook. Return value is wrapped in Optional since interpreter may not always be able to interpret the incoming event because of incorrect invocations. In such case, empty Optional should be returned. On successful interpretation, this method should return an Optional containing an instance ofObjectEventDetails
comprising following details –IdentifiableObject object
- The domain object for which event has been received. The class corresponding to domain object must implement IdentifiableObject interface and provide object ID & type accordingly.. In case of deletion events, fully populated object is not desired. Hence, an object ofcom.hcl.unica.system.model.DeletedEntity
containing the identifier of deleted object can be returned. Refer to the implementation ofinterpret
method inExampleEventInterpreterService
.ObjectEventType eventType
– The type of event.ObjectState transitionedState
– Current relevant state of the object. (As of release 12.1.2, transitionedState is ignored. It may be used in subsequent releases)
Plugin must extend its event interpreter service from the
com.hcl.unica.system.integration.service.object.event.ObjectEventInterpreterService
class for the successful exposure of webhook by the Content Integration Framework. On successful creation of event interpreter service, Content Integration Framework exposes an endpoint URL in following format relative to the application context root. The HTTP methods supported by this URL are guided by thegetRequestSpec
method -/api/AssetPicker/webhook/{SYSTEM_ID}/events/{eventName}/{contentId}
Wherein,
- {SYSTEM_ID} represents the identifier of the respective system.
- /{eventName}/{contentId} represents the relative URL configured in getRequestSpec method. eventName & contentId forms the path variables in this example.
Webhook security
All the webhooks exposed in Content Integration Framework are protected by default.
See API Security Filter (link to See API Security Filter configuration in Unica
Platform Admin Guide to learn more about API security. If none of the authentication
mechanisms suites the need of Plugin, then event interpreter service can override
validate
method to perform custom authentication &
authorization. Refer the implementation of validate
method in
ExampleEventInterpreterService
class to get a brief idea about
custom authentication. It demonstrates the use of Platform’s user data source for
maintaining API credentials. The USERNAME & PASSWORD constants represent the
authentication information received in webhook request, either by means of request
headers or embedded in the request body itself.