Human-in-the-Loop Configuration

The HumanInTheLoop section configures Synentra's Human-in-the-Loop (HITL) workflow.

When enabled, requests that exceed the configured risk threshold are suspended instead of being forwarded immediately to the upstream service. Operators can then review, approve, or deny the request through the HITL API.

---

Configuration hierarchy

HumanInTheLoop
├── Enabled
├── Threshold
├── TimeoutSeconds
├── MaxPendingRequests
└── Notifications
    ├── Slack
    ├── Teams
    ├── PagerDuty
    └── GenericWebhook

---

Properties

Property	Type	Default	Description
Enabled	bool?	true	Enables or disables the Human-in-the-Loop system globally
Threshold	double?	0.8	Risk score (0–1) above which requests require manual approval
TimeoutSeconds	int	3600	Time (seconds) before a pending HITL request automatically expires
MaxPendingRequests	int	100	Maximum number of pending HITL requests. 0 means unlimited
Notifications	object	{}	Notification channel configuration

---

Notifications

The Notifications object configures one or more external systems that should be notified whenever a request enters Human-in-the-Loop review.

Multiple notification channels may be enabled simultaneously.

Notification delivery is best-effort:

• Failure to deliver one notification does not prevent the HITL request from being created.
• Other notification channels are still attempted.
• Operators can always retrieve pending requests through the HITL API.

---

Slack

Sends notifications using a Slack Incoming Webhook.

Properties

Property	Type	Default	Description
Enabled	bool	false	Enable Slack notifications
WebhookUrl	string?	null	Slack Incoming Webhook URL
Channel	string?	null	Optional channel override
Username	string?	"Synentra HITL"	Bot display name
IconEmoji	string?	":robot_face:"	Bot icon emoji

Notification contents

Slack notifications include:

• HITL request ID
• Agent ID
• HTTP method
• Request URL
• Risk reason
• Expiration time
• Timestamp

---

Microsoft Teams

Sends notifications through a Microsoft Teams Incoming Webhook.

Properties

Property	Type	Default	Description
Enabled	bool	false	Enable Teams notifications
WebhookUrl	string?	null	Teams Incoming Webhook URL
ThemeColor	string?	"0076D7"	Card accent color (hex)

Notification contents

Teams notifications contain the same information as Slack notifications and are sent using the legacy MessageCard format.

---

PagerDuty

Creates incidents using the PagerDuty Events API v2.

Properties

Property	Type	Default	Description
Enabled	bool	false	Enable PagerDuty notifications
RoutingKey	string?	null	PagerDuty Events API v2 integration (routing) key
ApiUrl	string	"https://events.pagerduty.com/v2/enqueue"	PagerDuty Events API endpoint
Severity	string	"warning"	Alert severity (info, warning, error, critical)

Notification contents

The HITL request information is included under payload.custom_details.

---

Generic webhook

Sends a JSON payload to any HTTP endpoint.

Properties

Property	Type	Default	Description
Enabled	bool	false	Enable generic webhook notifications
WebhookUrl	string?	null	Endpoint that receives a POST request
Headers	Dictionary<string,string>?	null	Optional HTTP headers included with the request

The webhook receives a JSON document describing the suspended request.

---

Example

{
  "HumanInTheLoop": {
    "Enabled": true,
    "Threshold": 0.75,
    "TimeoutSeconds": 7200,
    "MaxPendingRequests": 50,
    "Notifications": {
      "Slack": {
        "Enabled": true,
        "WebhookUrl": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "Channel": "#security-reviews",
        "Username": "Synentra HITL Bot",
        "IconEmoji": ":shield:"
      },
      "Teams": {
        "Enabled": true,
        "WebhookUrl": "https://outlook.office.com/webhook/YOUR-WEBHOOK-URL",
        "ThemeColor": "FF0000"
      },
      "PagerDuty": {
        "Enabled": true,
        "RoutingKey": "your-routing-key",
        "Severity": "warning"
      },
      "GenericWebhook": {
        "Enabled": true,
        "WebhookUrl": "https://hooks.example.com/synentra-hitl",
        "Headers": {
          "X-Synentra-Token": "your-shared-secret"
        }
      }
    }
  }
}

---

Human-in-the-Loop workflow

When the Decision Engine determines that a request exceeds the configured risk threshold, Synentra suspends the request instead of immediately forwarding it to the upstream service.

The workflow is as follows:

1. The DecisionEngine evaluates the request.
2. A risk score is computed.
3. If the score exceeds Threshold, the engine returns a Hitl decision.
4. The HitlService stores the complete request in the configured cache with a TTL equal to TimeoutSeconds.
5. Synentra responds with HTTP 202 Accepted and returns a Location header pointing to /hitl/{id}.
6. Configured notification channels are invoked.
7. An operator reviews the request.
8. The operator calls either:
   • POST /hitl/{id}/approve
   • POST /hitl/{id}/deny
9. If approved, Synentra replays the original request against the upstream service.
10. If denied or expired, the request is discarded.

For the complete operator API, see Human-in-the-Loop.

---

Generic webhook payload

When Generic Webhook notifications are enabled, Synentra sends an HTTP POST request with a JSON payload similar to the following:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agentId": "...",
  "method": "DELETE",
  "url": "https://api.example.com/users/all",
  "reason": "High risk score: 0.92",
  "timestamp": "2025-01-01T12:00:00Z",
  "expiresAt": "2025-01-01T14:00:00Z"
}

---

Operational considerations

• Choose a Threshold that balances security and operational overhead. Lower values increase the number of requests requiring manual review.
• Configure at least one notification channel in production to ensure operators are alerted promptly.
• TimeoutSeconds should be long enough for operators to review requests but short enough to prevent stale approvals.
• Setting MaxPendingRequests to 0 removes the limit on pending requests. Consider monitoring storage usage if this option is used.
• Notification failures do not block request suspension or prevent operators from retrieving pending requests through the HITL API.