Connector SDK - External Webhooks Integration
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.
Core Functionality & Configuration
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.
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 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
Test 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 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 message queue. The payload can be processed if the ’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 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}
