웹훅이란 무엇인가요? 워크플로우에 웹훅을 설정하는 방법

웹훅은 정의된 조건이 충족될 때 제3자 앱이나 웹사이트로 HTTP 요청을 보내는 이벤트 기반 트리거입니다. 간단히 말해, 웹훅은 조건이 충족되었을 때 웹페이지나 제품에 변경을 가할 수 있는 자동화입니다. Freshsales에서는 웹훅을 사용하여 제3자 웹사이트로 데이터를 보내거나 트리거 조건에 따라 CRM 내에 새 레코드를 생성할 수 있습니다. 예를 들어, 거래가 체결되었을 때 자동으로 송장을 보내도록 웹훅을 설정할 수 있습니다.

이 워크플로우는 제3자 송장 생성 도구를 사용하여 구현할 수 있습니다. Invoiced에서 제공하는 무료 송장 생성 도구를 사용해 보겠습니다. Invoice Generator는 사용자가 전문적인 송장을 생성하고 보낼 수 있도록 하는 송장 템플릿을 제공합니다. 또한 API 호출을 지원하여 웹훅 사용 사례의 일부로 사용할 수 있습니다.

워크플로우:

참고: 웹훅을 설정하려면 REST API에 대한 기본적인 이해가 필요합니다. 코딩에 익숙하지 않다면 웹훅 설정을 위해 개발자의 도움을 받는 것이 좋습니다. 이 사용 사례에서는 Invoiced의 Invoice Generator가 선택되었습니다. 이는 등록된 사용자가 무료로 API를 통해 송장을 생성할 수 있도록 하기 때문입니다. 도구에 대한 더 나은 이해를 위해 Invoiced의 API 문서를 참조하십시오.

이제 예제를 기반으로 웹훅을 설정하는 방법을 이해해 보겠습니다. 연락처 조건에 따라 새로운 거래를 생성합니다. 웹훅은 워크플로우의 작업의 일부로 트리거됩니다. 워크플로우 트리거 및 조건을 설정하는 방법을 배우려면 이 문서를 참조하십시오.

웹훅의 구성 요소

웹훅 설정은 다음을 구성하는 것을 포함합니다:

요청 유형
콜백 URL
인코딩 유형
콘텐츠

요청 유형

Freshsales API는 표현 상태 전송(REST)을 지원합니다. 이는 CRM에서 데이터를 읽고, 수정하고, 추가하거나 삭제하는 'RESTful' 작업을 수행하는 API를 설정할 수 있음을 의미합니다. 웹훅을 구성할 때 다음 요청 유형 중 하나를 선택할 수 있습니다:

요청 유형	목적
POST	객체 생성
GET	하나 이상의 객체 가져오기
PUT/PATCH	객체 업데이트
DELETE	객체 제거

참고: 각 제3자 앱은 요청 유형을 다르게 사용하지만 대부분의 애플리케이션은 표준 방법을 따릅니다. 예를 들어, 우리는 Freshsales에 거래를 생성하기 위해 API 요청을 게시하고 있으므로 POST를 선택합니다.

콜백 URL

API 요청에 의해 타격을 받는 앱 또는 웹 서비스의 URL을 콜백 URL이라고 합니다. 예를 들어, 거래를 생성하려고 하므로 거래 페이지 URL을 사용할 수 있습니다. 송장을 생성하기 위한 Invoice Generator 콜백 URL: https://invoice-generator.com

인증(선택 사항): 콜백 URL이 인증을 요구하는 경우 사용자 이름과 비밀번호 또는 API 키를 추가할 수 있습니다. 예를 들어, Invoiced는 API 또는 사용자 이름-비밀번호를 통한 인증을 요구하지 않습니다.

콘텐츠와 함께 보안 세부 정보, API 버전 세부 정보 등을 포함하려면 사용자 정의 헤더 추가를 클릭하십시오. 사용자 정의 헤더는 다음 형식으로 헤더-값 쌍으로 입력해야 합니다: X-Sample-CustomHeader1: VALUE.

참고:

헤더에 공백이 포함된 경우 트리거가 실행되지 않습니다. 예를 들어, X-Sample Custom Header1: VALUE. 그러나 헤더 끝에 공백이 입력된 경우(X-Sample-CustomHeader1 : VALUE), 이는 무시됩니다.
하나 이상의 값을 가진 헤더는 구분 기호로 구분해야 합니다(쉼표나 콜론 사용 금지).
두 번째 헤더를 추가하려면 다음 줄에 사용자 정의 헤더와 값 쌍을 입력하십시오.

인코딩 유형

JSON, XML 또는 X-FORM-ENCODED 중에서 선택하십시오.

콘텐츠

웹훅의 일부로 필드 또는 엔드포인트의 두 가지 유형의 콘텐츠를 보낼 수 있습니다. 웹훅 요청의 일부로 보내야 하는 간단하거나 고급 콘텐츠(거래 세부 정보)를 선택하십시오.

간단: 선택한 레코드 유형의 필드를 선택하여 웹훅의 일부로 보냅니다. 간단한 유형에서는 웹훅이 미리 정의된 형식으로 데이터를 보내며, 이는 데이터를 보내고자 하는 API 엔드포인트의 형식과 일치하지 않을 수 있습니다. 따라서 항상 고급 옵션을 선택하는 것이 좋습니다.

고급: 콜백 URL로 엔드포인트를 보낼 수 있습니다. 엔드포인트는 콜백 URL에서 전달되는 코드/정보의 조각을 의미합니다. 관련 API를 사용하여 자리 표시자로 엔드포인트를 생성하십시오. 다양한 작업에 대한 API를 찾으려면 Freshsales 개발자 문서를 참조하십시오. 예를 들어, 거래 가치와 영업 소유자를 사용하여 거래에 대한 새 송장을 생성할 수 있습니다.

요청 유형	필드
GET 또는 DELETE	콜백 URL(필수), 인증 매개변수(선택 사항), 사용자 정의 헤더(선택 사항)
POST, PUT 또는 PATCH	콜백 URL(필수), 인증 매개변수(선택 사항), 사용자 정의 헤더(선택 사항), 인코딩(필수), 콘텐츠 유형(필수), 콘텐츠(필수)

자리 표시자:

연락처 워크플로우에 대한 웹훅을 생성할 때 필드에 사용할 수 있는 자리 표시자는 연락처와 연결된 기본 계정에서만 사용할 수 있습니다. 계정 워크플로우에 대한 웹훅을 생성할 때는 계정 필드만 사용할 수 있습니다. 거래 워크플로우에 대한 웹훅을 생성할 때는 거래 및 관련 계정에 대한 자리 표시자가 제공됩니다.

웹훅이 트리거되면 Freshsales에서 새 거래가 생성된 영업 계정으로 송장이 전송됩니다.

웹훅 테스트

웹훅을 구성한 후 버튼을 클릭하여 웹훅을 테스트하십시오. 구성이 올바르면 성공 메시지를 받게 됩니다. 잘못 구성된 경우 오류 코드가 표시될 수 있습니다. 오류 코드를 이해하고 이를 해결하려면 이 문서를 참조하십시오.

오류 코드	오류 코드 유형	의미
301	영구적으로 이동됨	요청한 리소스가 영구적으로 다른 URL로 이동되었습니다.
302	임시로 이동됨	요청한 리소스가 임시로 다른 URL로 이동되었습니다.
400	잘못된 요청	보낸 요청이 잘못되었습니다(구문에 잘못된 매개변수가 있거나 크기가 너무 클 수 있음).
401	권한 없음	리소스에 접근할 권한이 없습니다. 인증이 실패했거나 제공되지 않았습니다.
403	금지됨	요청이 올바르지만 요청된 작업을 수행할 권한이 없습니다.
404	찾을 수 없음	요청한 리소스를 현재 사용할 수 없습니다.
405	허용되지 않는 방법	요청한 리소스에 대해 요청 방법이 지원되지 않습니다.
409	충돌	서버의 다른 요청과 충돌하여 요청을 처리할 수 없습니다.
422	처리할 수 없는 엔티티	요청이 올바르게 구성되었지만 서버가 포함된 지침을 처리할 수 없습니다.
429	너무 많은 요청	최근에 너무 많은 요청을 보냈습니다.
500	내부 서버 오류	서버가 내부 오류 또는 잘못된 구성에 직면했습니다.
502	잘못된 게이트웨이	서버가 게이트웨이/프록시이며 업스트림 서버로부터 잘못된 응답을 받았습니다.

읽기 시간 초과 오류 Freshsales에서 웹훅이 트리거되면 6초 이내에 응답을 기대합니다. 응답을 받지 못한 경우 이 오류가 발생합니다. 그 이후에 API가 성공할 수 있습니다.

참고: 위에 추가된 오류 코드는 가장 일반적으로 보고된 것입니다. 이는 포괄적인 목록이 아닙니다. 제3자 애플리케이션에 특정한 오류는 웹훅 실패의 원인을 식별하기 위해 각 개발자 문서를 검사해야 합니다.

일반적으로 웹훅을 테스트할 때 자리 표시자를 사용하는 경우 샘플 데이터만 전송됩니다. 이는 제3자 엔드포인트로 API를 트리거할 때는 작동할 수 있지만, 전달된 자리 표시자의 유형에 따라 테스트 시 404 또는 400 오류를 발생시킬 수 있습니다.

{{contact.id}}/{{sales_account.id}}/{{deal.id}} 자리 표시자를 사용할 때, 테스트는 "12345"와 같은 테스트 데이터만 전송하며, 이는 올바른 ID가 아니므로 "404 Not Found 오류"를 발생시킵니다.

날짜 필드/태그 등에 대한 자리 표시자를 사용할 때, API를 통해 특정 형식으로 데이터를 전달해야 하는 경우, 웹훅을 테스트하면 "400 Bad Request 오류"를 발생시킬 수 있습니다.

웹훅만 테스트하는 것보다 워크플로우를 테스트하여 실제 데이터가 자리 표시자를 통해 전달되어 웹훅이 올바르게 설정되었는지 확인하는 것이 좋습니다.