External operations
Submit registered HTTP, MCP and signed webhook operations from an App container.
External operations
Use Nexia\Integrations\Contracts\ExternalIntegrations for an operation that a workspace administrator registered and explicitly shared with your App. Core holds the destination and credentials. The current human actor must have connection-use permission; an App installation alone does not grant it.
Submit after committing App work
In an App work handler, declare integration.submit and integration.result in its platform_callbacks. Call outside the App database transaction, using the invocation's current actor. The container runtime sends authenticated callbacks to Core; App code does not import Core models or obtain connection credentials.
use Nexia\Integrations\Contracts\ExternalIntegrations;
// Inside authorized App work, after its business transaction has committed.
$external = app(ExternalIntegrations::class);
$executionId = $external->submit($actor, $operationPublicId, ['order' => $orderId], $requestKey);
$result = $external->result($actor, $executionId);Use a durable business request key and preserve it when retrying submission. Identical input returns the same execution; changed input with the same key is rejected. Submission returns an ID, not remote success. Poll through bounded, scheduled App work, not a tight loop.
| Status | Meaning |
|---|---|
| queued / running | Waiting or executing |
| retrying | A signed webhook is waiting for its next bounded delivery attempt |
| succeeded | The registered operation returned success |
| failed | A remote failure was returned, or webhook attempts ended |
| cancelled | Current authorization, installation or configuration no longer permits execution |
| unknown | The remote effect may have happened; reconcile before a new request |
Only the originating App and actor with current access can read the result. Do not log its business payload. Core checks current permissions, App sharing and configuration revisions before execution; revocation cannot recall a request already sent.
Process Tasks and incoming messages
Administrators may select registered operations directly in Process service Tasks. Apps do not need to declare another Work Action for the same connection. Core waits for the external result and delivers it through the durable Process inbox.
Receiving endpoints are separate credentials and principals scoped to one legal entity, process definition and message-waiting step. Issuing a key does not grant receiving authority. API requests use Bearer authentication and Idempotency-Key; signed webhooks use webhook-id, webhook-timestamp and webhook-signature over the exact body. Both carry process_instance_id, payload and an optional reference_id. A 202 receipt acknowledges delivery acceptance, not overall process completion. The endpoint does not start a process or expose arbitrary resource CRUD.
MCP OAuth and mail ownership
Remote MCP credentials may use discovered OAuth authorization-code flows with PKCE S256. Core supports public-client registration where advertised, or registered clients using none, client_secret_basic or client_secret_post. Core stores and refreshes tokens; an App receives neither tokens nor client secrets and needs no OAuth callback of its own. Providers requiring other client authentication methods or lacking compatible discovery need a different supported authentication method. Revocation in Nexia removes local credentials; provider grant revocation remains separate.
Business mail still uses the owning email contracts and tenant/Legal Entity SMTP. Agent email is a Core tool with exact-content confirmation, live permission checks and encrypted delivery evidence, not a new unrestricted App mail API. Account-access system messages use a fixed Core allowlist and platform sender. Tenant administrators can inspect unified mail metadata with tenant.notification_delivery.read; this does not expose message bodies or grant business-resource access. SMTP acceptance does not establish inbox delivery.