외부 동작 호출

워크스페이스 관리자가 등록하고 해당 App에 명시적으로 공유한 동작을 Nexia\Integrations\Contracts\ExternalIntegrations로 실행합니다. 목적지와 인증 정보는 Core가 보관합니다. 현재 사용자에게 연결 사용 권한이 필요하며, App 설치만으로 권한이 생기지는 않습니다.

App 작업 커밋 후 제출

App 작업 핸들러의 platform_callbacks에 integration.submit과 integration.result를 선언합니다. App 데이터베이스 트랜잭션 밖에서 현재 호출의 사용자를 전달하세요. Container runtime이 인증된 콜백으로 Core를 호출하므로 App에서 Core 모델을 참조하거나 연결 인증 정보를 읽지 않습니다.

코드 예시

PHP

use Nexia\Integrations\Contracts\ExternalIntegrations;

// 권한이 확인된 App 작업에서 업무 트랜잭션이 커밋된 후 실행합니다.
$external = app(ExternalIntegrations::class);
$executionId = $external->submit($actor, $operationPublicId, ['order' => $orderId], $requestKey);
$result = $external->result($actor, $executionId);123456

업무 요청별로 유지되는 요청 키를 사용하고 재제출할 때도 같은 키를 전달하세요. 같은 입력은 기존 실행을 반환하며, 같은 키에 다른 입력을 보내면 거부됩니다. 제출 결과는 실행 ID이며 외부 처리 성공을 뜻하지 않습니다. 결과는 제한된 간격의 예약된 App 작업으로 확인하고 반복문에서 계속 조회하지 마세요.

상태	의미
queued / running	대기 또는 실행 중
retrying	서명된 웹훅의 다음 전송 시도 대기
succeeded	등록한 동작의 성공 응답 수신
failed	외부 실패 응답 또는 웹훅 시도 한도 도달
cancelled	현재 권한·설치·설정에서 실행할 수 없음
unknown	외부 처리가 이미 일어났을 수 있으므로 새 요청 전 대조 필요

최초 요청 App과 현재 권한이 있는 요청 사용자만 결과를 읽습니다. 업무 결과 본문을 로그에 남기지 마세요. Core는 실행 직전 권한·App 공유·설정 버전을 확인합니다. 권한을 회수해도 이미 전송한 요청을 취소할 수는 없습니다.

업무 Task와 외부 메시지 수신

관리자는 업무 프로세스 서비스 Task에서 등록한 동작을 직접 선택할 수 있습니다. 같은 연결을 위해 App이 Work Action을 다시 선언할 필요는 없습니다. Core가 외부 결과를 기다린 뒤 영속적인 프로세스 수신함으로 결과를 전달합니다.

수신 주소는 법인·프로세스 정의·메시지 대기 단계에 한정된 별도 인증 정보와 주체를 사용합니다. 키 발급과 수신 권한 부여는 별개입니다. API는 Bearer 인증과 Idempotency-Key를, 서명된 웹훅은 원문 본문에 대한 webhook-id·webhook-timestamp·webhook-signature를 사용합니다. 본문에는 process_instance_id, payload, 선택 항목인 reference_id를 보냅니다. 202 접수 응답은 전체 업무 완료가 아닙니다. 이 주소는 프로세스 시작이나 임의 리소스 조회·수정 기능을 제공하지 않습니다.

MCP OAuth와 메일 소유권

외부 MCP 인증 정보는 검색된 인증 서버의 OAuth Authorization Code와 PKCE S256을 사용할 수 있습니다. Core는 서버가 제공하는 공개 클라이언트 등록 또는 사전 등록된 클라이언트의 none, client_secret_basic, client_secret_post 인증을 지원합니다. 토큰 저장·갱신은 Core가 담당합니다. App은 토큰이나 Client Secret을 받지 않으며 별도의 OAuth 콜백도 구현하지 않습니다. 다른 인증 방식이나 호환되지 않는 검색 규격을 요구하는 공급자는 지원되는 다른 인증 방식을 사용해야 합니다. Nexia의 인증 정보 폐기와 공급자에서의 앱 승인 철회는 별개입니다.

업무 메일은 기존 소유 계약과 테넌트·법인의 SMTP를 사용합니다. 에이전트 메일은 정확한 내용 승인, 현재 권한 확인, 암호화된 발송 기록을 사용하는 Core 도구이며 무제한 App 메일 API가 아닙니다. 계정 접근용 시스템 메일은 Core의 고정 허용 목록과 플랫폼 발신자를 사용합니다. tenant.notification_delivery.read 권한으로 통합 발송 메타데이터를 조회할 수 있지만 본문 노출이나 관련 업무의 접근 권한까지 부여하지는 않습니다. SMTP 접수는 수신함 도착을 뜻하지 않습니다.