Events Subscription

When working with APIs that broadcast events-related messages and you subscribed to events notifications, you implement a server compliant to the events specification. This server processes messages sent by the core systems through FusionFabric.cloud. Events specifications are compliant with the OpenAPI specification.

You need to set the message that you receive from FusionFabric.cloud in a business context for your users, using an UI. You can find an example that follows this client-server architecture in the Events Notification Application Tutorial.

Register an API with Events

To register an API with events

  1. From the API catalog, bookmark an API with events.
  2. Start the application wizard with the bookmarked API.
  3. In the Events tab, use an URL that is publicly available as the Events Base URL. This is the {{eventsBaseUrl}} of the listener endpoints, specified in the events specifications.

The base URL is used to convert the relative URLs of the Events specification endpoints into absolute web URLs. Use a valid URL, that can be accessed over the Internet – URLs pointing to localhost are not allowed.

  1. Register your application. You are ready to implement your server to process the messages.

If you permanently disable the server backend, or the base URL is not available for any other reason, you must unsubscribe from the events notifications from your dashboard on FusionCreator.

As your first priority for implementation, you must make sure that your webhook URL is successfully validated during the application registration and active afterwards, during periodical validation checks. You learn about that in the next section.

Get Your Webhook URL Validated

Prior to sending the first event message, and then periodically, FusionFabric.cloud sends you a request with the purpose of validating the webhook URL you registered with your application.

This request is send to the OPTIONS endpoint that you must implement in your client application, as documented in the events reference documentation of the API you registered.

Sample of Events specification showing the endpoint used by FusionFabric.cloud to verify your webhook URL

This request from FusionFabric.cloud is not signed, you don’t need to perform additional checks on it. It’s only after your implementation is compliant to the events specification, and you respond with a valid response, FusionFabric.cloud will start sending you the event message that you must validate as described in the next section.

Validate the Event Message

FusionFabric.cloud implements a security mechanism that allows you to verify, in your client applications, that messages are sent by FusionFabric.cloud. This applies to client applications that subscribed to event notifications attached to APIs.

When the message is sent to the subscriber - your client application, FusionFabric.cloud performs a byte level validation of the request body payload, and signs the message. The signature contains:

  • a private key that is added to a dedicated request header, named Header
  • the tenant id
  • the event id, type and time

Upon receiving an event message via the webhook URL you registered with your application, your client applications must:

  • Check message authentication: validate that the message came from FusionFabric.cloud.
  • Check message integrity: validate the signature of the message itself.

Both actions should be done in one step - you can verify the signature with the paired public key issued by FusionFabric.cloud. The public key is exposed in JWKS format at the following endpoint:

url

Non-repudiation is handled by the hash-based message authentication code (HMAC) of the messages you receive, using the public key shared through the above endpoint, and the hash covering the message body.

The HMAC specifications of the messages broadcasted by FusionFabric.cloud are:

  • RS256 (RSA Signature with SHA-256 Hash function) - an asymmetric algorithm that uses a public/private key pair.
  • Hash input: raw bytes of event message body.

For a hands-on experience with an implementation of the message signature validation, check out our sample application on GitHub.