External webhooks & custom actions

Choose the action you want to connect #

An outbound action webhook lets Korenact ask your external server to perform an authorized operation. Your server can then call a CRM, ticket system, business API, or automation service. This is separate from inbound Telnyx callbacks.

You can connect a registered action such as intake.create to its existing system kind, or use Custom actions with external.request for a named operation. Custom operations always require staff approval. An action must be enabled on its agent, allowed by its rules, granted the required data scopes, and enabled on its webhook connection.

The signed-in action catalog at /api/v1/catalog/actions lists every registered key, system target, required field, and data scope. The agent's rules remain authoritative. Webhook transfers to humans are excluded; staff transfers use telephony and routing settings.

Install server settings in the root .env #

1. Host an HTTPS action endpoint and a separate read-only health endpoint on your external server.
2. Add the exact approved hostname to the root EXTERNAL_WEBHOOK_ALLOWED_HOSTS list. Multiple hosts are comma-separated; wildcard hosts are not accepted.
3. Generate a signing secret with openssl rand -hex 32. Keep the same secret privately on both servers.
4. Read the client's real organization ID from its authenticated organization API response.
5. Install a JSON secret under KORENACT_INTEGRATION_<ORG_ID_UPPER>_CUSTOM_SERVER. Replace the organization placeholder with the actual uppercased ID.
6. Recreate API and webhook-worker containers after changing the environment.

EXTERNAL_WEBHOOK_ALLOWED_HOSTS=api.your-company.com
EXTERNAL_WEBHOOK_TIMEOUT_SECONDS=10
# Replace ORG_ID_UPPER with the actual organization ID.
KORENACT_INTEGRATION_ORG_ID_UPPER_CUSTOM_SERVER='{"url":"https://api.your-company.com/korenact/actions","health_url":"https://api.your-company.com/korenact/health","bearer_token":"YOUR_SERVER_TOKEN","signing_secret":"YOUR_RANDOM_SIGNING_SECRET","operations":["notify_dispatch","create_ticket"]}'

Only public HTTPS endpoints on port 443 are supported. URLs with embedded credentials, query strings, fragments, or private DNS addresses are rejected. Redirects are not followed. Connections are pinned to validated public IP addresses while retaining hostname certificate verification. Put API authentication in the optional bearer token, not the URL. A custom operation must be listed in operations; the caller cannot choose an arbitrary destination or operation.

Connect the webhook in Korenact #

1. Open Connections → Connect a system.
2. Choose Custom actions for named operations, or the existing system kind for registered actions.
3. Choose Provider External webhook.
4. Enter a display name and Credential reference custom_server.
5. For Custom actions, set Enabled action keys to external.request and Fields sent to your server to operation,request.
6. For built-in actions, enter their registered keys and explicit field names. Every action must match the selected system kind, and its required fields must be included.
7. Select Connect. The health endpoint must return HTTP 200 with {"ok":true}.
8. Enable the action and its request type on the responsible agent. Grant its required action permissions and data scopes in the attached rules.

For a custom operation, enable Custom external action, Run a custom external action, rule permission external.request, and data scope external.execute. Staff approval is mandatory even if the rule's approval checkbox is off. Use one verified connection per system kind.

Request contract and signature verification #

Korenact posts this JSON envelope. Only explicitly enabled payload fields are included. Internal state and the full transcript are excluded.

{
  "event": "action.requested",
  "organization_id": "org_example",
  "action_id": "act_example",
  "action_type": "external.request",
  "payload": {"operation": "create_ticket", "request": "The reception printer is not working"}
}

The headers include Idempotency-Key: act_example, X-Korenact-Timestamp as Unix seconds, and X-Korenact-Signature: sha256=HEX_DIGEST. If configured, Authorization is Bearer YOUR_SERVER_TOKEN.

Verify the signature over timestamp + "." + raw_request_body using HMAC-SHA256 and the shared signing secret. Compare the digest in constant time. Validate timestamp freshness, the bearer token when present, organization ownership, allowed action types, operation names, and payload fields before doing any work. Use the exact raw bytes rather than re-serializing JSON.

Persist the action ID in your server before executing. Repeated deliveries with the same ID must return the original result instead of repeating the operation. A stable ID identifies the same action; it does not authorize another organization's task.

Return a completed confirmation #

After the external operation finishes, return HTTP 200 with this confirmation:

{"ok":true,"status":"completed","external_ref":"ticket_12345"}

The reference must be a nonempty identifier up to 160 characters using letters, digits, colon, period, underscore, slash, or hyphen. Extra response data is not copied into the conversation. The action is executed only after this completed confirmation.

An explicit HTTP rejection is failed. HTTP 202, HTTP 408, server errors, timeouts, oversized or unreadable responses, missing references, and incomplete confirmations are held as Outcome unknown. Staff must reconcile your server's records before issuing another action. Korenact does not automatically retry uncertain operations. Asynchronous completion callbacks are not implemented by this adapter; use a synchronous bounded endpoint or staff reconciliation.

Test a custom operation step by step #

1. Configure a harmless allowed operation on a controlled server.
2. Start a conversation with the responsible agent or its team.
3. Enter Run action create_ticket: The reception printer is not working. The explicit command supplies the operation and request. Vague custom requests are clarified through the normal field collection.
4. Review the proposed operation in Queue. Confirm its details, then approve it as an owner, administrator, or supervisor.
5. Inspect your server's signature verification and idempotency logs. Confirm that its API received only the enabled fields.
6. Review the confirmed reference in the Korenact action record.
7. Test a rejected operation, missing details, and an uncertain response. Confirm staff reconciliation rather than an automatic repeat.

Tenant-scoped credentials are resolved on the backend. Secret values, webhook URLs, and authorization headers are never returned by the Connections API. Public client documentation contains examples only.