Zapier, Make, n8n 연동하기

연동 플랫폼은 코드 없이 Sursa를 수백 개의 다른 도구와 연결해 줘요. Sursa 전용 앱은 필요 없어요. 플랫폼의 범용 HTTP 요청 단계와 웹훅 단계가 API와 바로 동작해요. 이 가이드에서는 가장 흔한 세 가지 방법을 다뤄요.

어떤 플랫폼을 쓰든 키는 단계 자체가 아니라 플랫폼의 자격 증명 저장소나 연결 저장소에 보관하세요. 그래야 키가 모든 시나리오와 실행 로그에 복사되지 않아요.

항목을 카드로 보내기

Sursa에서 사용자 지정 소스를 만들고(Sources → New source → Custom source), 소스 페이지의 API keys 섹션에서 그 소스의 키를 만드세요. 키는 kbsrc_로 시작하며 이 소스에 문서를 쓰는 일만 할 수 있으므로, 외부 플랫폼에 보관하기에 알맞은 키예요.

흔히 쓰는 구성은 “X에서 항목이 생성되거나 업데이트되면 Sursa로 보내기”예요.

{
  "external_id": "{{record_id}}",
  "title": "{{record_title}}",
  "content": "{{record_body_html}}",
  "content_type": "html",
  "url": "{{record_link}}",
  "path": "{{record_category}}",
  "updated_at": "{{record_updated_at}}"
}

• 항목의 고정된 ID를 external_id에 매핑하고, 시각이나 실행 번호는 절대 쓰지 마세요. 그러면 같은 항목을 다시 보낼 때 같은 카드가 업데이트되고, 단계를 재시도해도 문제가 없어요. 이때 응답은 unchanged예요.
• “항목 삭제” 트리거에는 메서드 DELETE와 URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}로 두 번째 워크플로를 추가하세요.
• GET https://api.example.com/v1/push/sources/42와 같은 Authorization 헤더로 연결을 테스트하세요. 소스의 이름과 문서 수를 반환해요.

문서 필드는 코드에서 쓸 때와 같아요.

Zapier

Webhooks by Zapier → Custom Request를 사용하세요.

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: 끄세요. Data: 트리거의 필드를 넣은 위의 JSON.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

HTTP → Make a request 모듈을 사용하세요.

• Method: POST, URL: 위와 같음, Headers: Authorization: Bearer kbsrc_….
• Body type: Raw, Content type: JSON (application/json), Request content: 값을 매핑한 위의 JSON.
• 이후 모듈에서 result(created, updated, unchanged)를 쓰려면 Parse response를 켜세요.
• 파일을 보내려면 Body type에서 Multipart/form-data를 고르고, file 필드(이전 모듈의 파일)와 content를 뺀 JSON 필드를 담은 document 텍스트 필드를 넣으세요.

n8n

HTTP Request 노드를 사용하세요.

• Method: POST, URL: 위와 같음.
• Authentication: Generic Credential Type → Header Auth. 이름은 Authorization, 값은 Bearer kbsrc_…예요.
• Send Body: 켬, Body Content Type: JSON. 필드는 {{ $json.id }} 같은 표현식으로 매핑하세요.

예약된 전체 내보내기에는 HTTP Request 노드 세 개를 이어 붙이세요. 동기화를 열고(처음에는 {"type": "initial"}, 그 뒤에는 {"type": "incremental"}과 함께 POST …/syncs), 항목을 보내고, {"status": "complete"}로 동기화를 닫아요. n8n은 항목마다 노드를 한 번씩 실행해요. 요청 수를 줄이려면 Aggregate 노드로 항목을 묶어 {"sync_number": …, "documents": [...]} 형식으로 …/documents/batch에 보내세요.

워크플로에서 질문하기

워크플로에서 Sursa에 질문하고 답변을 활용할 수 있어요. 지원 티켓의 답장 초안을 쓰거나, CRM 항목에 정보를 보강하거나, 채팅 채널에 답변을 올릴 수 있어요. ask 스코프와 필요한 컬렉션을 볼 수 있는 역할이 있는 조직 API 키를 쓰세요.

응답의 answer에는 답변(Markdown)이, sources에는 출처가 담기며 각 출처에는 doc_name이 있어요. 지식 베이스에 질문에 관한 내용이 없으면 empty가 설정돼요(예: no_hits). 워크플로가 빈 답변을 올리지 않도록 필터 단계를 추가하세요. Q&A 봇 만들기를 참고하세요.

답변에는 몇 초가 걸릴 수 있어요. 플랫폼의 HTTP 단계에 기본 타임아웃이 짧게 설정되어 있다면 최소 60초로 늘리세요.

Sursa 이벤트로 워크플로 시작하기

모든 플랫폼이 웹훅을 받을 수 있어요.

1. 트리거를 만들고 트리거가 제공하는 HTTPS 주소를 복사하세요.
2. Sursa의 Administration → Integrations → Webhooks and API에서 또는 POST /v1/webhooks로, 그 주소와 원하는 이벤트를 지정해 웹훅을 등록하세요.
3. 웹훅 페이지에서 테스트 이벤트를 보내고, 다음 단계에서 이벤트의 필드(type, data.card.title, …)를 매핑하세요.

서명을 확인하세요. 트리거 주소는 공개되어 있어서 주소를 아는 사람은 누구나 요청을 보낼 수 있어요. 특히 워크플로가 데이터를 바꾼다면, 처리하기 전에 각 전송의 서명을 검증하세요.

• n8n에서는 Webhook 노드 뒤에 웹훅 수신하기의 Node.js 서명 검증 코드를 담은 Code 노드를 추가하고, 정확한 바이트를 쓸 수 있도록 Webhook 노드의 원본 본문(raw body) 옵션을 켜세요.
• 원본 본문에 접근하기 어려운 Zapier와 Make에서는 최소한 주소를 비밀로 유지하고, type으로 필터링하고, 처리하기 전에 API로 객체를 다시 읽으세요.

재시도와 중복은 다른 수신 서버와 마찬가지로 플랫폼에도 적용돼요. 같은 실행이 중복되면 문제가 생기는 경우 이벤트의 id로 필터링하세요.

팁

• 429가 오면 플랫폼의 자동 재시도가 Retry-After에 적힌 초만큼 기다리게 하세요. 대량 내보내기에는 배치를 쓰세요.
• 플랫폼은 모든 요청과 응답을 기록해요. 키를 URL에 넣지 말고, 워크플로가 문서를 쓰기만 한다면 kbsrc_ 키를 쓰세요.
• 단계가 401 sources.push_key_invalid 오류로 실패하면 URL의 소스 ID가 키와 맞는지 확인하세요.