HTTP Handlers extend Link with custom HTTP endpoints. They allow external applications and trading partners to submit messages, retrieve information, or invoke business logic when the built-in APIs do not cover an integration’s requirements.
Handlers are implemented as Link artifacts and hosted by Link. Two types are available: regular HTTP Handlers and Advanced HTTP Handlers.
Typical use cases
-
Receive a webhook or a partner-specific request.
-
Validate an incoming document and return an immediate acknowledgement.
-
Read metadata from custom headers, query parameters, or the request URL.
-
Expose data or operations that are not available through the built-in APIs.
Choosing a handler type
|
Type |
Suitable for |
|---|---|
|
HTTP Handler |
A focused endpoint, such as a webhook receiver, where the implementation handles the incoming request and constructs the response. |
|
Advanced HTTP Handler |
A custom API with explicitly mapped routes and HTTP methods, parameter binding, request validation, and Swagger documentation. |
Advanced HTTP Handlers can map input from the request body, route, query parameters, and headers. They provide a structured approach to exposing multiple operations within one artifact.
Authentication and access
Regular HTTP Handlers and Advanced HTTP Handlers have different built-in access models. Authentication identifies the calling Link user; the handler’s access model determines whether that user may invoke it.
See API Authentication for details about OAuth and Personal Access Tokens (PATs).
HTTP Handlers
When Built-in security is enabled, the caller must authenticate as a Link user and have the API Generic Http Handler permission (API_GenericHttpHandler).
This permission is included in the API Generic Http Handler role. The role is not assigned to any user groups by default, so access must be explicitly granted through the calling user’s group and role assignments.
For example, when using a dedicated service account:
-
Assign the account to an appropriate user group.
-
Ensure that the group has a role containing
API_GenericHttpHandler. -
Authenticate requests using that account.
Successful authentication alone is insufficient: the user must also have the required permission. This is a general API permission rather than an access setting for an individual handler.
Advanced HTTP Handlers
Advanced HTTP Handlers provide access settings for each configured handler:
|
Configuration |
Built-in access requirement |
|---|---|
|
Built-in security enabled, no Authorized user-group selected |
The caller must authenticate as a Link user. |
|
Authorized user-group selected |
The caller must authenticate and belong to the selected group. Selecting a group implicitly enables built-in security. |
|
Built-in security disabled, no group selected |
These settings do not require Link authentication. The implementation must provide any required access controls. |
Use Authorized user-group to restrict a handler to its intended users or service accounts.
Additional authorization
Access to a handler does not define which business operations or data the caller should be allowed to access. Implement any additional operation-specific permissions, data restrictions, and business rules within the handler.
When built-in security is disabled, provide appropriate authentication and authorization in the implementation.
Development guides
Before creating a new handler, check whether an existing system artifact or Link Community Component covers your requirements.
-
How to develop Link 3 artifacts — Development setup, HTTP Handler base classes, configuration, and dependency injection.
-
Advanced HTTP Handlers — Route mapping, parameter binding, validation, error handling, Swagger documentation, and configuration in Link.