웹훅 입력, 실행과 인증 설정
웹훅은 실행 시 받은 입력을 외부 요청에 넣고, 외부 응답에서 출력 값을 추출합니다. 액션, 함수 또는 애플리케이션이 이 입력과 출력을 사용합니다. 소스에는 연결과 인증 정보를 두고 웹훅에는 개별 요청 및 실행 정책을 구성합니다.
입력 매개변수
액션에 웹훅을 연결할 때는 액션 매개변수를 웹훅 입력에 매핑합니다. Functions on Objects로 입력을 계산하는 경우 반환형을 WebhookInput | undefined처럼 구성할 수 있습니다. 매핑 함수가 undefined를 반환하면 해당 웹훅을 실행하지 않습니다.
| 자료형 | 의미와 제약 |
|---|---|
Boolean | true 또는 false입니다. |
Integer | 정수 값입니다. |
Long | Long 자료형의 정수 값입니다. |
Double | Double 자료형의 숫자 값입니다. |
String | 텍스트입니다. 허용할 특정 문자열 값들로 제한할 수 있습니다. |
Date | 날짜 값입니다. |
Timestamp | 시각 값입니다. |
List | 지정한 자료형의 값들을 순서가 있는 목록으로 받습니다. |
Record | 키와 값의 묶음입니다. 필수 키와 각 값의 자료형을 지정할 수 있습니다. |
Optional | 입력이 제공되지 않는 경우를 허용합니다. |
Attachment | 액션 양식에서 업로드한 파일입니다. 에이전트 워커 소스에서는 지원하지 않습니다. |
출력 추출과 호출 간 참조
외부 시스템이 반환한 ID 같은 값을 출력 매개변수로 정의하면 액션에서 이를 받아 Foundry 객체에 쓸 수 있습니다. 추출 가능한 값은 실행하는 작업 유형의 응답에 따라 달라집니다.
한 웹훅 안의 뒤쪽 요청에서 앞선 응답을 직접 참조할 수도 있습니다. 예를 들어 다음과 같은 가상 응답의 results.unique_id 값을 후속 요청의 헤더에 넣는 경우입니다.
{
"results": {
"unique_id": "ID4567"
}
}
- 두 번째 Call의
Headers값 입력란에서@를 입력합니다. From a call을 선택하고 첫 번째 Call을 지정합니다.Extract by key를 선택하여results를 입력합니다.Add nested key로unique_id를 추가합니다.Add를 선택하여 참조를 삽입합니다.
기본 추출 방식은 다음과 같습니다.
| 방식 | 결과 |
|---|---|
Whole response | 응답 전체를 문자열로 추출합니다. 설정한 기대 자료형에 따른 변환도 적용할 수 있습니다. |
Extract by key | 객체 응답에서 키를 선택합니다. 중첩 키를 순서대로 지정할 수 있습니다. |
Extract by index | 배열 응답의 위치를 선택합니다. 인덱스는 0부터 시작합니다. |
Test Connection으로 성공한 응답을 받은 뒤 출력 매개변수를 추가하면 응답에서 해석한 출력 후보가 제시됩니다.
일부 결과는 출력 자료형에 맞춰 자동 변환됩니다.
- 출력이
String인데 작업 결과가 문자열이 아니면 JSON 문자열로 변환합니다. - 출력이
Record인데 작업 결과가 문자열이면 그 문자열을 JSON으로 파싱하려고 시도합니다. - 출력이
Double이면Integer와Long결과를 자동 변환합니다.
REST API 요청
REST API 소스의 요청 편집기에서 다음 항목을 구성합니다.
| 항목 | 필수 여부 | 의미 |
|---|---|---|
Method | 필수 | 실행할 HTTP 메서드입니다. |
Relative path | 선택 | 소스에 등록한 도메인을 기준으로 하는 엔드포인트 경로입니다. |
Query Params | 선택 | 쿼리 매개변수의 키와 값입니다. 소스 설정에서 실행 시 추가하는 항목은 읽기 전용으로 표시됩니다. |
Authorization | 선택 | 소스의 인증 설정을 사용합니다. 인증 방식을 바꾸려면 소스에서 수정합니다. |
Headers | 선택 | 요청 헤더의 키와 값입니다. 소스 설정에 따라 자동으로 추가되는 헤더는 읽기 전용으로 표시됩니다. |
Body | 선택 | 본문을 받는 요청에 사용할 내용과 형식입니다. |
본문 형식은 Raw JSON, Form Data, Form URL Encoded, 바이너리 File, XML, Plain Text, HTML을 지원합니다. 하나의 웹훅에 여러 Call을 두고 앞선 응답 값을 다음 Call의 경로, 헤더나 본문에 참조할 수 있습니다.
Task body와 소스별 방식
Task로 구현된 웹훅의 Task body는 실행할 Task에 전달할 데이터입니다. 해당 Task 유형이 요구하는 스키마에 맞춰 Handlebars 문법으로 구성하며, 정의한 웹훅 입력 매개변수를 참조할 수 있습니다.
SAP 웹훅은 SAP ERP의 작업별 설정을 사용합니다. 기존 사용자 지정 YAML 소스를 운영하는 경우에는 SAP Custom source의 웹훅 계약을 적용합니다. SAP 웹훅에도 Foundry 관리 클라우드에서 실행하는 Foundry 워커를 권장합니다.
Salesforce 연동은 REST API 소스로 구성합니다. 기존 Salesforce 소스를 이전하는 절차는 Salesforce 연결에 있습니다. magritte-rest-v2 기반의 이전 REST 구성을 새 연동에 사용하지 않습니다.
실행 제한
| 제한 | 설정과 동작 |
|---|---|
| Time limit | 최대 실행 시간입니다. 지정하지 않으면 20초이며, 설정 가능한 최댓값은 180초입니다. 외부 시스템의 응답이 지연되면 시간 초과 오류를 표시합니다. |
| Concurrency limit | 동시에 실행할 수 있는 웹훅 수입니다. 외부 시스템에 과도한 동시 요청이 몰리는 것을 제한합니다. |
| Rate limit | 지정한 시간 창 안의 실행 횟수를 제한합니다. 초, 분, 시간 또는 일 단위의 횟수 제한을 설정할 수 있습니다. |
시간 초과는 외부 시스템이 아무 변경도 하지 않았다는 뜻이 아닙니다. 요청이 전달된 이후 응답이 오지 않은 경우에는 외부 상태를 확인하고 재실행 여부를 판단해야 합니다.
웹훅을 함수로 게시
생성할 때 Function configuration을 켜거나, 기존 웹훅의 같은 설정에서 함수 게시를 활성화합니다. 활성화한 이후 만들어지는 웹훅 버전은 함수 버전으로도 게시됩니다. 이 작업은 되돌릴 수 없으며 웹훅에서 게시한 함수를 삭제할 수 없습니다.
게시한 함수는 Workshop, OSDK, 함수 기반 액션, Machinery, Automate 및 다른 함수에서 호출할 수 있습니다. TypeScript v2나 Python 함수에서 웹훅을 사용하려면 먼저 웹훅을 함수로 게시한 뒤 해당 함수를 저장소에 가져오고 OSDK로 호출합니다. TypeScript v1의 소스 가져오기와 생성된 webhook 메서드를 사용하는 방식은 함수 연동에 설명합니다.
권한과 실행 이력
웹훅 생성, 설정 및 삭제 권한은 연결된 소스의 권한을 따릅니다. Data Connection 권한에서 소스와 웹훅의 작업별 권한을 확인합니다.
실행 이력에는 호출한 사용자 ID, 시각, 성공 또는 실패 상태가 기록됩니다. 기본적으로 입력값과 전체 응답은 해당 웹훅을 호출한 사용자만 볼 수 있습니다. 다른 사용자의 상세 이력을 보려면 webhooks:read-privileged-data 권한을 포함한 사용자 지정 역할이 필요합니다. 이 권한은 기본적으로 어떤 사용자에게도 부여되지 않습니다.
응답은 기본적으로 6개월 동안 이력에 보관됩니다. 전체 응답은 실행한 사용자와 webhooks:read-privileged-data 권한을 가진 사용자가 볼 수 있습니다. 민감한 응답을 반환하는 웹훅에서는 응답 저장을 끌 수 있습니다. 토큰 발급 Call처럼 특히 민감한 결과를 반환하는 호출은 저장 여부를 별도로 확인합니다.
OAuth 2.0 authorization code grant
사용자별 OAuth 인증이 필요하면 Control Panel에 외부 인증 애플리케이션(Outbound application)을 구성합니다. REST API 소스의 인증 방식에 이 애플리케이션을 지정하면, 웹훅을 실행하는 사용자가 OAuth 서버에 인증하도록 요청할 수 있습니다.
오류별로 다음 구성을 확인합니다.
| 오류 | 확인할 설정 |
|---|---|
The client is not authorized to request an authorization code | OAuth 클라이언트가 authorization code grant를 사용하도록 등록되어 있어야 합니다. Foundry의 third-party application을 OAuth 클라이언트로 사용하는 경우 Developer Console에서 Authorization code grant를 활성화합니다. |
The provided redirect URI is not an allowed redirect URI | authorization code 설정의 Redirect URI와 외부 인증 애플리케이션의 리디렉션 페이지 URL이 정확히 일치해야 합니다. |
리디렉션 경로는 플랫폼 기본 URL 아래의 /workspace/oauth2-clients/callback입니다. 예를 들어 가상 플랫폼 주소가 https://example.palantirfoundry.com이면 전체 주소는 https://example.palantirfoundry.com/workspace/oauth2-clients/callback입니다. 실제 설정에는 외부 인증 애플리케이션 화면에 표시된 정확한 URL을 등록합니다.
OAuth 2.0 client credentials grant
앱의 장기 비밀 정보로 단기 액세스 토큰을 얻은 뒤 업무 API를 호출하는 흐름은 하나의 웹훅에 두 Call을 연결하여 구성할 수 있습니다. 준비할 값은 토큰 서버의 도메인과 토큰 경로, 업무 API의 도메인과 경로, Client ID와 Client Secret입니다. 토큰 서버와 업무 API가 같은 도메인일 수도 있습니다.
소스 준비
REST API 소스의 Domains에 토큰 서버와 업무 API 도메인을 모두 추가합니다. 토큰 교환을 Call에서 직접 수행하므로 소스의 자동 인증 방식은 선택하지 않습니다. Additional secrets에 ClientSecret을 저장하고 요청에서 그 값을 참조합니다. 비밀 정보는 암호화되어 보관되며, 소스 편집 및 소유 화면에서도 원래 값을 노출하지 않습니다.
토큰 요청과 업무 요청
첫 번째 Call은 토큰 엔드포인트를 호출합니다. 일반적인 구성은 POST, Form URL Encoded 본문과 다음 필드입니다.
| 필드 | 값 |
|---|---|
grant_type | client_credentials |
client_id | 등록한 애플리케이션의 실제 Client ID |
client_secret | 소스의 ClientSecret 비밀 정보 참조 |
서버에 따라 추가 필드나 다른 이름, 별도 클라이언트 인증 방식이 필요할 수 있습니다. 예를 들어 Microsoft Graph는 scope에 https://graph.microsoft.com/.default를 사용합니다. 해당 토큰 서버의 계약에 맞춰 요청합니다.
POST는 기본적으로 Write API로 분류됩니다. 반복해도 업무 데이터 변경을 일으키지 않는 토큰 발급 요청이라면 요청 오른쪽에서 Read API로 지정할 수 있습니다. 실제 데이터 변경 요청을 단지 제한을 피하려고 Read로 분류해서는 안 됩니다. 여러 요청에 걸친 트랜잭션을 보장할 수 없으므로 일반적으로 한 웹훅에서 여러 Write API Call은 허용하지 않습니다.
두 번째 Call에는 업무 API의 실제 메서드, 경로와 본문을 구성합니다. Headers에 Authorization을 추가하고, 값에는 Bearer 를 먼저 입력한 뒤 @ 메뉴의 From a call로 첫 Call의 응답을 선택합니다. Extract by key에서 토큰 키를 지정합니다. 일반적인 키는 access_token이지만 서버가 반환하는 실제 키를 사용합니다.
토큰 응답 보관
Storage and retention에서 첫 번째 Call의 전체 응답 저장을 끄는 것을 권장합니다. 저장하면 액세스 토큰이 상세 이력 열람 권한을 가진 사용자에게 노출될 수 있습니다. 토큰 엔드포인트를 인식하면 응답 저장을 끄도록 제안하는 안내가 표시될 수 있습니다.