Bitrix24 작업 위젯 설치 및 런타임 핸들러 - n8n 워크플로우

설치 및 토큰 관리를 위한 안정적인 백엔드가 필요한 Bitrix24 애플리케이션 개발자
복잡한 웹훅 연동을 위한 강력한 n8n 템플릿이 필요한 사용자
CRM 환경 내에 커스텀 위젯을 배포하는 자동화 전문가
Bitrix24 API 처리를 위한 자체 호스팅 솔루션을 찾는 엔지니어

Bitrix24와 같은 플랫폼용 커스텀 애플리케이션을 개발하려면 OAuth 토큰, 설치 콜백, 동적 콘텐츠 전송에 대한 복잡한 처리가 필요합니다. 이 강력한 n8n 워크플로우는 커스텀 위젯 애플리케이션과 관련된 모든 Bitrix24 이벤트를 처리하는 중앙 핸들러 역할을 하여 이러한 문제를 해결합니다. 이 n8n 템플릿의 핵심 가치는 설치 핸드셰이크(중요 액세스 토큰을 디스크에 저장)를 원활하게 관리하고, 런타임 시 저장된 자격 증명을 활용하여 Bitrix24 작업 보기 탭 내에서 작업 세부 정보와 같은 상황별 정보를 가져와 표시하는 능력에 있습니다.

Bitrix24가 설치 또는 위젯 표시를 위해 요청을 보낼 때마다 이 특정 n8n 노드 설정은 안전한 인증과 즉각적이고 맞춤화된 응답을 보장하며, 잘 설계된 n8n 워크플로우의 효율성을 보여줍니다.

전체 프로세스는 Bitrix24로부터의 POST 요청을 수신 대기하는 지정된 n8n 트리거인 웹훅 노드에서 시작됩니다.

1. 트리거 및 초기화: Bitrix24 Handler n8n 트리거가 이벤트를 수신합니다. Extract Credentials n8n 노드는 수신된 JSON 페이로드를 즉시 파싱하여 도메인, 액세스 토큰 및 리프레시 토큰을 검색합니다.


2. 이벤트 식별: Check Event Type 코드 노드는 요청을 분석하여 애플리케이션 설치 이벤트(ONAPPINSTALL)와 런타임 배치 요청(예: 작업 보기)을 구별합니다.


3. 설치 경로: 설치인 경우 워크플로우가 분기됩니다. 설치가 아직 완료되지 않았다면 시스템은 Set Settings Data n8n 노드를 사용하여 토큰을 포맷하고, 이를 JSON 파일(Create Settings File)로 변환한 다음, Save Installation Settings n8n 노드(Read/Write File)를 사용하여 구성을 저장합니다. 그런 다음 Register Placement HTTP 요청 노드를 통해 위젯 배치를 등록하고 Installation Response 웹훅 응답으로 프로세스를 완료합니다.


4. 런타임 경로(위젯 표시): 이벤트가 런타임 요청인 경우, 시스템은 Read Installation Settings 및 Extract Installation Settings n8n 노드를 사용하여 이전에 저장된 인증 데이터를 검색합니다. Merge request data with installation settings 노드는 필요한 데이터 컨텍스트를 준비합니다.


5. 데이터 처리 및 검색: Process Settings 함수 노드는 taskId와 같은 컨텍스트별 정보를 추출합니다. Has Valid Settings? If 노드는 자격 증명을 검증합니다. 유효한 경우 Get Task Data HTTP 요청 n8n 노드는 저장된 Bitrix24 액세스 토큰을 사용하여 Bitrix24 API에 상세 작업 정보를 쿼리합니다.


6. 응답 생성: Format Task Data 함수 노드는 원시 작업 데이터를 구조화된 HTML로 변환합니다. 마지막으로 Task View Response n8n 노드가 이 HTML을 Bitrix24로 다시 보내고, Bitrix24는 이를 커스텀 작업 위젯 내에 렌더링합니다. 설정이 유효하지 않은 경우 대신 Error Response가 반환됩니다. 이 복잡한 로직은 n8n 워크플로우의 강력한 활용 사례를 보여줍니다.

이 포괄적인 n8n 워크플로우를 배포하려면 다음 단계를 따르십시오:

1. n8n 워크플로우 가져오기: 제공된 JSON 데이터를 복사합니다. n8n 인스턴스에서 'Workflows'로 이동하여 'New'를 클릭합니다. 'Import from JSON'을 선택하고 코드를 붙여넣습니다.


2. 웹훅 트리거 구성: Bitrix24 Handler n8n 트리거 노드를 찾습니다. 경로는 bitrix24/widgethandler.php로 설정되어 있습니다. 워크플로우를 활성화하여 전체 웹훅 URL을 생성합니다. 이 URL은 설치 및 배치 이벤트의 핸들러 URL로 Bitrix24 애플리케이션 설정에 등록해야 합니다.


3. 플레이스홀더 자격 증명 설정: Extract Credentials n8n 노드에는 하드코딩된 플레이스홀더 값(예: local.67b8a796e92127.82791242)이 포함되어 있습니다. 이는 일반적으로 설치 웹훅 중에 Bitrix24의 실제 데이터로 덮어쓰여지지만, 애플리케이션이 다른 정적 클라이언트 ID/비밀 키를 사용하는 경우 조정해야 할 수 있습니다. Bitrix24 앱이 이러한 초기 토큰을 보내도록 올바르게 구성되었는지 확인하세요.


4. 파일 시스템 접근: 이 워크플로우는 ReadWriteFile n8n 노드를 사용하여 Bitrix24 인증 토큰을 저장하고 읽습니다. n8n 호스트 환경이 /data/files/hotline_files/ 경로에 접근할 수 있는 필요한 권한을 가지고 있는지 확인하거나(Extract Credentials 노드의 settingsFilePath 변수를 n8n 인스턴스에서 접근 가능한 위치로 조정하세요).


5. 활성화: n8n 워크플로우를 저장하고 활성화합니다. 이제 자동화가 Bitrix24 이벤트를 수신 대기합니다.

Bitrix24 Handler (Webhook n8n 트리거): n8n 워크플로우의 진입점입니다. 특정 경로로 들어오는 POST 요청을 수신하도록 구성되어 설치 및 작업 보기 요청 모두에 대한 일련의 작업을 시작합니다.
Extract Credentials (Set n8n 노드): 보안에 필수적인 이 노드는 Bitrix24가 보낸 동적 인증 매개변수(accesstoken, refreshtoken 등)를 추출하여 후속 HTTP 요청 및 스토리지 저장을 위해 준비합니다.
Check Event Type (Code n8n 노드): 수신된 요청 본문을 파싱하여 앱 설치 콜백과 위젯 배치 이벤트를 구별하는 커스텀 스크립팅 노드로, n8n 워크플로우에 중요한 흐름 제어 로직을 제공합니다.
Is Installation? (If n8n 노드): 현재 요청이 애플리케이션 설치 프로세스(isInstallation: true)의 일부인지 여부에 따라 흐름을 지시하는 핵심 로직 n8n 노드입니다.
Set Settings Data & Save Installation Settings (Set & ReadWriteFile n8n 노드): 이 노드들은 n8n 템플릿 내에서 함께 작동하여 새로 수신된 Bitrix24 토큰(만료일 및 도메인 포함)을 직렬화하고 로컬 파일 시스템의 JSON 파일에 안전하게 기록하여 향후 런타임 사용을 위한 영속성을 보장합니다.
Register Placement (HTTP Request n8n 노드): Bitrix24 API 호출을 실행하여 커스텀 위젯 핸들러 URL을 원하는 배치, 특히 TASKVIEWTAB에 바인딩함으로써 n8n 웹훅 URL이 Bitrix24 인터페이스에 올바르게 통합되도록 합니다.
Read Installation Settings & Process Settings (ReadWriteFile & Function n8n 노드): 런타임 접근 시 이 노드들은 저장된 토큰을 검색하고 처리하여, n8n 워크플로우가 API 조회를 진행하는 데 필요한 자격 증명과 컨텍스트(특정 taskId 등)를 확보하도록 합니다.
Get Task Data (HTTP Request n8n 노드): 검증된 액세스 토큰을 사용하여 Bitrix24 API(tasks.task.get)에 인증된 호출을 수행하고 위젯 표시에 필요한 세부 정보를 가져옵니다. 이는 이 n8n 워크플로우의 런타임 단계에서 중요한 단계입니다.

• Task View Response (RespondToWebhook n8n 노드): 런타임 요청에 대한 최종 작업입니다. 이전 함수 노드에서 생성된 HTML을 패키징하여 즉시 Bitrix24로 다시 보내고, Bitrix24는 이를 커스텀 작업 위젯 내에 렌더링합니다. 설정이 유효하지 않은 경우 대신 Error Response가 반환됩니다. 이 복잡한 로직은 n8n 워크플로우의 강력한 활용 사례를 보여줍니다.