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)

The following are the specialized interfaces and classes available for the object event interpreter service:
  • 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 from ObjectEventInterpreterService 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 of ExampleEventInterpreterService, 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 the Content-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 type ObjectEventListenerRequestSpec. The ObjectEventListenerRequestSpec is essentially the partial specification of webhook���s signature. The ObjectEventListenerRequestSpec wraps an object of InboundHttpRequestSpec, 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 the getRequestSpec implementation in ExampleEventInterpreterService. Runtime values for these path variables can be obtained from InboundHttpRequestContext. 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 of ObjectEventDetails 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 of ObjectEventDetails 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 of com.hcl.unica.system.model.DeletedEntity containing the identifier & type of deleted object can be returned. Refer to the implementation of interpret method in ExampleEventInterpreterService.
    • 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 the getRequestSpec 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.