Webhooks

Webhooks let Operator integrate with external systems. They should be treated as production integration points, not demo shortcuts.

Webhook security

Webhooks should use secrets or tokens scoped to each integration. Polaris uses that information to validate that a request comes from an authorized source before processing external actions.

For sensitive actions, pair webhooks with human approvals. Polaris can prepare the action, ask for confirmation when needed and reduce the risk of invalid external calls.

Best practice: Never share secrets in public channels or include them in examples, screenshots or documents visible to end users.

Recommended contract

• Use HTTPS.
• Return a stable JSON response.
• Make the operation idempotent.
• Include correlation IDs in logs.
• Validate payloads before mutating external state.

{
  "event": "operator.action.requested",
  "workspace_id": "workspace_123",
  "correlation_id": "req_123",
  "payload": {}
}

Failure behavior

Failed webhooks should surface as failed tool executions or failed jobs, depending on runtime mode.