Webhook Configuration

Last verified with: 10.8.6.0

Overview

LogiSense outbound webhooks let an external system subscribe to selected business events and receive an HTTP call when that event occurs.

At a high level:

1. An administrator creates an event subscription with a webhook binding.
2. The subscription references exactly one webhook configuration.
3. The webhook configuration defines the destination URL, HTTP verb, authentication method, and payload format.
4. When the subscribed event occurs, LogiSense sends a predefined outbound request body for that webhook integration.
5. LogiSense delivers the request to your endpoint and records delivery history for monitoring and retry.

This guide is written for teams building the receiving side of the integration. Subscription setup is expected to be performed through the LogiSense administration UI.

Prerequisites And Access Assumptions

• You have a reachable HTTPS endpoint for production webhook delivery.
• You have access to the LogiSense administration help documentation that explains how to configure the event subscription and webhook action in the UI.

Subscription Setup

Configure the event subscription and webhook action through the LogiSense administration UI.

This guide intentionally does not duplicate the administration workflow. Instead, use your linked help documentation for:

• creating the event subscription
• selecting the event to subscribe to
• attaching the webhook action
• setting the destination URL and authentication

From the consumer side, the important behavior is that each webhook subscription resolves to one active webhook destination that points to your receiving endpoint.

Integration Model

The subscription setup and the delivery behavior are related but different:

• The event subscription identifies the event and whether the subscription is active.
• The webhook configuration identifies where LogiSense sends the request and how it authenticates.
• The webhook payload is defined by LogiSense for the integration and is not intended to be customized by external consumers through the standard administration flow.

Webhook Destination Settings

When a webhook subscription is configured, the main settings that affect your receiving system are:

• destination URL: the HTTPS endpoint that LogiSense calls when the event occurs
• HTTP method: the outbound method used for delivery
• authentication mode: how LogiSense authenticates to your endpoint
• payload format: the format selected for the outbound request
• predefined payload: the request body sent by LogiSense for the subscribed webhook event

Current Limits

Current behavior and limits include:

• each event subscription has one webhook destination
• supported outbound methods are POST and PUT
• the subscription must be configured with a webhook destination before events can be delivered

Authentication Modes

LogiSense currently supports four outbound webhook authentication modes:

• OAuth 2.0 Password
• Key Value Pair
• None
• OAuth 2.0 Client Credentials

No Authentication

This mode sends the webhook without an authentication credential managed by LogiSense.

Use this only when the receiving endpoint is protected by some other control, such as:

• private network routing
• an upstream gateway
• IP allowlisting
• another trusted transport boundary

For internet-facing integrations, an authenticated mode is usually the safer choice.

Key Value Pair Authentication

This mode is intended for receivers that expect a static key name and secret value, commonly as a custom HTTP header.

This is often the simplest secure option when:

• the destination system does not require OAuth
• the receiving platform supports custom shared-secret headers
• you want a straightforward credential that is easy to rotate and validate

On the consumer side, your endpoint should validate the expected key and secret before accepting the request.

OAuth 2.0 Password

This mode is intended for integrations where the destination platform protects the webhook receiver behind an OAuth 2.0 password grant flow.

This is generally used when the target platform expects LogiSense to obtain an access token by authenticating with a user-oriented credential set before sending the webhook request.

Use this mode only when the receiving platform explicitly requires password grant behavior, since newer integrations often prefer client credentials over password-based flows.

OAuth 2.0 Client Credentials

This mode is intended for machine-to-machine integrations where the receiving platform expects OAuth 2.0 client credentials grant authentication.

This is usually the preferred OAuth option for service-to-service webhook delivery because it avoids user-password style credentials and aligns better with modern integration patterns.

If the destination platform supports both OAuth approaches, client credentials is typically the better long-term choice for a backend webhook receiver.

Webhook Format Types

Available format types are:

• JSON
• Form URL Encoded

For current integrations, validate the final request behavior in a non-production environment before relying on format-specific handling by the receiving platform.

Webhook Payloads

Webhook payloads should be treated as predefined by LogiSense for the integration.

That means:

• The payload shape is determined by LogiSense.
• External consumers should not assume they can configure or redesign the request body through the normal administration workflow.
• Your receiving system should validate and process the payload as delivered.

Example webhook payload:

{
  "eventName": "{eventName}",
  "eventTime": "{currentDateTime}",
  "account": {
    "id": "{account.id}",
    "name": "{account.name}"
  },
  "invoice": {
    "id": "{invoice.id}",
    "name": "{invoice.name}",
    "total": "{invoice.invoiceTotal}",
    "dueDate": "{invoice.dueDate}"
  }
}

An example payload may include business identifiers, event metadata, and event-specific values such as account or invoice data, depending on the subscribed event.

Payload Handling Guidance

• Treat the webhook payload as an externally consumed contract.
• Include identifiers your downstream system can use for idempotency and correlation.
• Avoid assuming that every field appears on every event type.
• If your integration handles multiple event types, use fields such as eventName and event-specific identifiers to route and process the message correctly.

The list of available events and any event-specific payload reference should be maintained separately and linked from this guide.

Delivery Semantics

Webhook delivery works as follows:

• LogiSense creates an outbound HTTP request using the configured URL and request verb.
• The request body is sent as string content with media type application/json.
• Delivery attempts are recorded for monitoring and troubleshooting.
• Success is based on the HTTP response status of the target system.

Retry Behavior

In the current product behavior:

• 2xx responses are treated as successful.
• 400 Bad Request is treated as non-retryable.
• 401 Unauthorized is retried within the expected retry loop.
• Other retryable non-success statuses are treated as failures and may move into retry handling.

This means your receiver should treat webhook requests as potentially repeated and implement idempotent processing.

Listener Implementation Best Practices

Build your receiver with the following assumptions:

• The same webhook may be delivered more than once.
• Response timing should be fast.
• Business processing should be asynchronous when possible.
• Payload values are event-specific.

Recommended receiver behavior:

1. Authenticate the request using the agreed auth model.
2. Validate the payload enough to confirm it is structurally usable.
3. Record an idempotency key based on the business identifiers in the payload.
4. Return a 2xx response quickly after durable acceptance.
5. Process downstream work off the request thread.

Recommended status code handling:

• Return 200 OK, 202 Accepted, or another appropriate 2xx after durable acceptance.
• Return 400 Bad Request only when the payload is invalid and should not be retried.
• Return 401 Unauthorized only when the credential is wrong or expired.
• Return 5xx when the receiver is temporarily unavailable and the event should be retried.

Example receiver acknowledgment:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "accepted": true,
  "message": "Webhook received for asynchronous processing"
}

Monitoring And Troubleshooting

The Webhook Monitor is the primary operational screen for reviewing outbound delivery attempts and retry chains.

Use it to:

• review outbound sent webhook attempts
• inspect status and error outcomes
• investigate retry relationships
• retry failed outbound webhooks when the platform allows it

Important monitor behavior:

• The Sent view shows outbound webhook attempts.
• The Received view is for inbound callback or received webhook traffic.
• Retry is intended for failed outbound webhook entries.
• Retried records are linked back to the original webhook log entry.

When troubleshooting, check:

• destination URL correctness
• auth type and secret values
• whether the selected event actually occurred
• whether the receiving system is expecting the correct predefined payload for that event
• whether your receiver is returning a non-retryable 400

Consumer Recommendations

• Treat webhook payloads as a contract defined by LogiSense and consumed by your downstream system.
• Keep the receiving contract versioned on your side if multiple teams depend on it.
• Prefer HTTPS endpoints and secret-based authentication even when unauthenticated delivery is technically possible.
• Use correlation and business identifiers in the delivered payload to support traceability and idempotent processing.
• Validate integrations in a lower environment before relying on format-specific behavior in the receiving platform.