Connector SDK - External Webhooks Integration

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Topic

Author:

Fluent Commerce

Changed on:

13 Dec 2023

Overview

The Connect SDK offers seamless integration with webhooks, enabling you to receive messages and perform various actions based on incoming calls. This document provides an overview of the core features of the Connect SDK and outlines the steps to integrate it into your application.

Author:

Fluent Commerce

Changed on:

13 Dec 2023

Overview

Key points

The Core functionalities are included:
- Send HTTP Request
- Authentication Verification
- Message Queue Integration
Configuration

Core functionality

Send HTTP Request: The Connect SDK External Webhooks receive HTTP calls from the External Webhooks Endpoint. These calls contain a request payload with Authentication Context.
Authentication Verification: The Connect SDK External Webhooks feature must be used with our Web Security Module. The verification process utilizes an Authentication Filter to verify any client request. Follow this page for more details.
Message Queue Integration: Upon receiving an incoming webhook message, the SDK transforms the request payload into the Connect SDK's internal message format and places it into the message queue. This allows partners to leverage the power and scalability of message queues for efficient message processing.

What is the endpoint exposed for webhooks:

Connect SDK inherently provides an external webhook endpoint at `/api/v1/fluent-connect/external-system/webhook`. When operated locally on port 8080, the URL becomes `localhost:8080/api/v1/fluent-connect/external-system/webhook`. When deployed elsewhere, the URL becomes `\/api/v1/fluent-connect/external-system/webhook`

Configuration

By default, Connect SDK provides a list of default public endpoints and two custom authentication filters:

1  security:
2    web:
3      publicEndpoints:
4        - "/actuator/**"
5        - "/api/docs"
6        - "/swagger-ui.html"
7        - "/api/v1/fluent-connect/webhook"
8        - "/api/v1/fluent-connect/scheduler/**"
9      customAuthFilters:
10        - "com.fluentcommerce.connect.core.web.security.filters.ApiKeyAuthenticationFilter"
11        - "com.fluentcommerce.connect.core.web.security.filters.FluentOauthTokenAuthenticationFilter"

Testing the external webhook endpoint exposed by Connect SDK locally

Author:

Fluent Commerce

Changed on:

13 Dec 2023

Key Points

Proper setup and configuration for `connect-sdk-core-web-security` module: Connector Customization Guidelines
Customized Handler for handling Webhook request: Connector Customization Guidelines | Handlers.1
Connect SDK inherently provides a webhook endpoint at `/api/v1/fluent-connect/external-system/webhook`. When operated locally on port `8080`

Steps

Test the external webhook endpoint exposed by Connect SDK locally

Connect SDK inherently provides a webhook endpoint at `/api/v1/fluent-connect/external-system/webhook`. When operated locally on port 8080, the URL becomes `http://localhost:8080/api/v1/fluent-connect/external-system/webhook`. Any request directed to this endpoint is automatically filtered and authenticated by `connect-sdk-core-web-security` module and placed in the event message queue. The webhook payload can be processed if the webhook’s request body: `route` property aligns with any of the "message handler" provided.Webhook Request:Header:

1Authorization: <insert authorization value>
2fluent.account: <insert associated fluent account value>

Body:Below is the sample request body when calling the external webhook endpoint:

`route`: The defined handler for handling the webhook request.
`payload` : Data payload context that a defined Handler handles. The size limit for the `payload` data varies by the type of queue defined for the Connect SDK:
- SQS: 256KB
- Kafka: 1MB (default settings)
- GCP Pubsub: 10MB

1{
2  "route" : "your-defined-handler-route",
3  "payload" : {
4      // props 
5   }
6}

For example:

1{
2  "route" : "fc.connect.sample-weather-update",
3  "payload": {
4        "id":"demo-weather",
5        "code":"300",
6        "temperature":"40",
7        "description":"Hot Day"
8  }
9}

1@Component
2@HandlerInfo(name = "weather-update", route = "fc.connect.sample-weather-update")
3public class WeatherDataMessageHandler implements MessageHandler {
4    @Override
5    public void processMessage(@NotNull final MessageHandlerContext context) throws UnprocessableMessageException, HandlerRetryException {
6        UpsertSettingUtils.upsertSetting(getPayload(context), context, UpsertSettingUtils.FLUENT_SETTING_KEY);
7    }
8
9    protected WeatherData getPayload(final MessageHandlerContext context) {
10        // Extract data by defined Class `WeatherData`
11        final Optional<WeatherData> payload = context.getMessagePayload(WeatherData.class);
12        // Extract data by key-value 
13        final Optional<Map> payload = context.getMessagePayload(Map.class);
14        // Handling optional data...
15    }
16}

Fluent Commerce

Test the external webhook endpoint exposed by Connect SDK locally

1Authorization: <insert authorization value>
2fluent.account: <insert associated fluent account value>

Body:Below is the sample request body when calling the external webhook endpoint:

`route`: The defined handler for handling the webhook request.
`payload` : Data payload context that a defined Handler handles. The size limit for the `payload` data varies by the type of queue defined for the Connect SDK:
- SQS: 256KB
- Kafka: 1MB (default settings)
- GCP Pubsub: 10MB

1{
2  "route" : "your-defined-handler-route",
3  "payload" : {
4      // props 
5   }
6}

For example:

1{
2  "route" : "fc.connect.sample-weather-update",
3  "payload": {
4        "id":"demo-weather",
5        "code":"300",
6        "temperature":"40",
7        "description":"Hot Day"
8  }
9}

1@Component
2@HandlerInfo(name = "weather-update", route = "fc.connect.sample-weather-update")
3public class WeatherDataMessageHandler implements MessageHandler {
4    @Override
5    public void processMessage(@NotNull final MessageHandlerContext context) throws UnprocessableMessageException, HandlerRetryException {
6        UpsertSettingUtils.upsertSetting(getPayload(context), context, UpsertSettingUtils.FLUENT_SETTING_KEY);
7    }
8
9    protected WeatherData getPayload(final MessageHandlerContext context) {
10        // Extract data by defined Class `WeatherData`
11        final Optional<WeatherData> payload = context.getMessagePayload(WeatherData.class);
12        // Extract data by key-value 
13        final Optional<Map> payload = context.getMessagePayload(Map.class);
14        // Handling optional data...
15    }
16}

Connector SDK - External Webhooks Integration

Overview

Core Functionality & Configuration

Overview

Key points

Core functionality

What is the endpoint exposed for webhooks:

Configuration

Testing the external webhook endpoint exposed by Connect SDK locally

Test the external webhook endpoint exposed by Connect SDK locally

Key Points

Steps

Test the external webhook endpoint exposed by Connect SDK locally

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links

Test the external webhook endpoint exposed by Connect SDK locally