HubSpot 연락처 기반 워크플로우에서 웹훅을 트리거하는 방법

연락처 기반 워크플로우에서 웹훅을 사용하여 HubSpot과 외부 도구 간에 데이터를 전송하거나 가져올 수 있습니다. 이를 통해 서로 다른 플랫폼에 걸친 프로세스를 자동화할 수 있습니다. POST 웹훅을 사용하여 HubSpot에서 데이터를 전송하고, GET 웹훅을 사용하여 외부 도구에서 데이터를 가져올 수 있습니다.

POST 또는 GET 웹훅을 설정할 때, 속도 제한을 통해 웹훅 실행 속도를 제어하고, HubSpot 내에서 또는 외부 도구를 사용하여 웹훅 구성을 수동으로 테스트할 수 있습니다. 
또한 HubSpot에서 전송된 요청을 확인하는 방법, 웹훅을 사용하여 워크플로를 자동으로 시작하는 방법, 다른 워크플로 작업에서 웹훅 응답 데이터를 사용하는 방법도 알아볼 수 있습니다.

웹훅에 대한 자세한 내용은 개발자용 웹훅 문서에서 확인하세요. HubSpot과의 웹훅 구현과 관련하여 구체적인 질문이 있는 경우, HubSpot 개발자 포럼에 문의해 주세요.

웹훅의

대표적인 사용 사례에는

어떤 것들이 있나요?

웹훅의 대표적인 사용 사례는 다음과 같습니다.

• 사이트의 특정 양식을 작성한 HubSpot 연락처 데이터를 CRM과 같은 다른 시스템에 전송하는 경우.

• 구매 주문서를 생성하기 위해 거래 데이터를 외부 배송 처리 시스템으로 전송하는 경우.

• 다른 시스템에서 데이터를 가져와 HubSpot 레코드를 업데이트하는 경우.

워크플로를 사용하여 POST 및 GET 요청을 모두 보낼 수 있습니다. HubSpot은 웹훅 트래픽을 다른 워크플로 프로세스와 별도로 관리합니다. 이는 워크플로 및 웹훅 성능을 최적화하기 위함입니다. 웹훅이 느리거나 시간 초과가 발생하면 워크플로 작업이 예상보다 오래 걸릴 수 있습니다.

POST 웹훅을 사용하여 HubSpot에서 데이터를 전송하려면 어떻게 해야 하나요?

1. HubSpot 계정에서 더 보기를 클릭한 다음 자동화 > 워크플로로 이동하세요. 더 보기가 계정에 표시되지 않으면 바로 자동화 > 워크플로로 이동하세요.
2. 기존 워크플로를 편집하려면 워크플로 이름을 클릭하세요. 또는 새 워크플로를 생성하세요.
3. 워크플로 편집기에서 + 더하기 아이콘을 클릭하여 액션을 추가하세요.
4. 왼쪽 패널의 ‘데이터 운영(Data ops) ’ 섹션에서 ‘웹훅 보내기’를 선택합니다.
    

5. '메서드' 드롭다운 메뉴를 클릭하고 'POST'를 선택합니다.
6. 웹훅 URL을 입력합니다.
   • 웹훅 URL은 보안 프로토콜로 제한되며 HTTPS로 시작해야 합니다.
   • 특정 정보를 요청하려면 웹훅 URL에 ?queryparameter=abc와 같은 쿼리 매개변수를 추가할 수 있습니다 .
   • 쿼리 매개변수가 추가되지 않은 경우, 일반적인 POST 또는 GET 요청이 전송됩니다.
7. 웹훅에 대한 요청을 인증하도록 인증 유형을 설정하십시오. 웹훅 헤더에 요청 서명을 사용하거나 API 키를 사용할 수 있습니다:
   • 웹훅 헤더에 요청 서명을 사용하려면:
     • '인증 유형' 드롭다운 메뉴를 클릭합니다. 그런 다음 '헤더에 요청 서명 포함'을 선택합니다.
     • 그런 다음 HubSpot 앱 ID를 입력하세요. 요청 서명을 확인하는 방법을 알아보세요.
   • 인증에 API 키 또는 개발자 계정을 통해 생성된 공개 앱을 사용하려면:
     • 인증에 API 키를 사용할 경우, 사용되는 API 키 이름과 API 키 위치는 웹훅 구성 방식에 따라 달라집니다. 보안상의 이유로 테스트 요청에는 API 키가 표시되지 않습니다. API 키를 사용하려면:
       • '인증 유형' 드롭다운 메뉴를 클릭하십시오. 그런 다음 'API 키'를 선택하십시오.
       • API 키 이름을 입력하세요.
       • 'API 키 위치' 드롭다운 메뉴를 클릭합니다. 그런 다음 '쿼리 매개변수' 또는 '요청 헤더' 중 하나를 선택합니다. HubSpot에서 API 키 사용에 대해 자세히 알아보세요.
     • HubSpot API에 요청을 보내는 경우:
       • API 키 드롭다운 메뉴를 클릭하고 시크릿을 선택하십시오. 시크릿 값은 Bearer [YOUR_TOKEN] 형식이어야 합니다.
       • API 키 이름의 값을 'Authorization'으로 설정하십시오.
       • API 키 위치 의 값을 ‘요청 헤더 ’로 설정하십시오.
8. 모든 속성을 포함하려면 [객체]의 모든 속성 포함을 선택하십시오.
9. 특정 속성만 포함하려면:
   • '요청 본문 사용자 지정'을 선택하세요.
   • HubSpot 속성을 사용하여 요청 본문을 사용자 지정하려면 ‘키’를 입력하고 속성을 선택하십시오. 다른 속성을 추가하려면 ‘속성 추가’를 클릭하십시오.
   • 정적 필드를 사용하여 요청 본문을 사용자 지정하려면 키와 값을 입력하세요. 다른 속성을 추가하려면 ‘정적 값 추가’를 클릭하세요.
   • 속성이나 정적 값을 제거하려면 휴지통 삭제 아이콘을 클릭하세요.
10. 상단에서 '저장'을 클릭합니다.

참고: 여러 출력 항목을 선택하려면 응답이 JSON 객체 형식으로 구성되어야 합니다.

GET 웹훅을 사용하여 HubSpot으로 데이터를 가져오려면 어떻게 해야 하나요?

1. HubSpot 계정에서 더 보기를 클릭한 다음 자동화 > 워크플로로 이동하세요. 더 보기가 계정에 표시되지 않으면 바로 자동화 > 워크플로로 이동하세요.
2. 기존 워크플로를 편집하려면 워크플로 이름을 클릭하세요. 또는 새 워크플로를 생성하세요.
3. 워크플로 편집기에서 ‘+’ 아이콘을 클릭하여 액션을 추가하세요.
4. 왼쪽 패널의 ‘데이터 운영(Data ops )’ 섹션에서 ‘웹훅 보내기(Send a webhook)’를 선택하세요.
    

5. '메서드' 드롭다운 메뉴를 클릭하고 'GET'을 선택합니다.
6. 웹훅 URL을 입력합니다.
   • 웹훅 URL은 보안 프로토콜로 제한되며 HTTPS로 시작해야 합니다.
   • 특정 정보를 요청하려면 웹훅 URL에 ?queryparameter=abc와 같은 쿼리 매개변수를 추가할 수 있습니다 .
   • 쿼리 매개변수가 추가되지 않은 경우, 일반적인 POST 또는 GET 요청이 전송됩니다.
7. 웹훅에 대한 요청을 인증하도록 인증 유형을 설정하십시오. 웹훅 헤더에 요청 서명을 사용하거나 API 키를 사용할 수 있습니다:
   • 웹훅 헤더에 요청 서명을 사용하려면:
     • '인증 유형' 드롭다운 메뉴를 클릭합니다. 그런 다음 '헤더에 요청 서명 포함'을 선택합니다.
     • 그런 다음 HubSpot 앱 ID를 입력하세요. 요청 서명을 확인하는 방법을 알아보세요.
   • 인증에 API 키 또는 개발자 계정을 통해 생성된 공개 앱을 사용하려면:
     • 인증에 API 키를 사용할 경우, 사용되는 API 키 이름과 API 키 위치는 웹훅 구성 방식에 따라 달라집니다. 보안상의 이유로 테스트 요청에는 API 키가 표시되지 않습니다. API 키를 사용하려면:
       • '인증 유형' 드롭다운 메뉴를 클릭하십시오. 그런 다음 'API 키'를 선택하십시오.
       • API 키 이름을 입력하세요.
       • 'API 키 위치' 드롭다운 메뉴를 클릭합니다. 그런 다음 '쿼리 매개변수' 또는 '요청 헤더' 중 하나를 선택합니다. HubSpot에서 API 키 사용에 대해 자세히 알아보세요.
     • HubSpot API에 요청을 보내는 경우:
       • API 키 드롭다운 메뉴를 클릭하고 시크릿을 선택하십시오. 시크릿 값은 Bearer [YOUR_TOKEN] 형식이어야 합니다.
       • API 키 이름의 값을 'Authorization'으로 설정하십시오.
       • API 키 위치 의 값을 ‘요청 헤더 ’로 설정하십시오.
8. GET 요청을 설정하는 경우, HubSpot 속성을 사용하거나 쿼리 매개변수로 정적 값을 추가할 수 있습니다: 

9. HubSpot 속성을 쿼리 매개변수로 사용하려면:
   • '쿼리 매개변수' 섹션에서 '키'를 입력한 다음 속성을 선택합니다.
   • 다른 속성을 추가하려면 ‘속성 추가’를 클릭합니다.
   • 속성을 제거하려면 삭제 아이콘을 클릭하세요.
10. 정적 값을 쿼리 매개변수로 사용하려면:
    • '쿼리 매개변수' 섹션 에서 키를 입력한 다음 값을 입력합니다.
    • 다른 속성을 추가하려면 '정적 값 추가'를 클릭하십시오.
    • 속성을 제거하려면 삭제 아이콘을 클릭하십시오.
11. '저장'을 클릭합니다.

속도 제한을

통해 웹훅 실행 속도를 제어하려면 어떻게 해야 하나요?

속도 제한을 설정하여 웹훅 작업이 실행되는 속도를 결정할 수 있습니다. 이 속도 제한은 워크플로우 내의 모든 후속 작업에도 영향을 미칩니다.

1. HubSpot 계정에서 더 보기를 클릭한 다음 자동화 > 워크플로로 이동하세요. 더 보기가 계정에 표시되지 않으면 바로 자동화 > 워크플로로 이동하세요.
2. 워크플로우 이름을 클릭합니다.
3. 워크플로 편집기에서 ‘웹훅 보내기’ 액션을 클릭합니다.
4. 왼쪽 패널에서 ‘레이트 제한 구성’을클릭하여 해당 섹션을 펼치세요.
5. '레이트 제한 켜기' 스위치를 클릭하여 켭니다. 기본적으로 이 설정은 꺼져 있습니다. 
6. 레이트 제한을 설정합니다. 
   • 작업 실행 횟수: 기간당 최대 실행 횟수를설정합니다 . 
   • 시간 범위: 속도 제한의 시간 범위를 설정합니다. 이 시간 범위는 초(Seconds), 분( Minutes) 또는 시간(Hours) 단위로 설정할 수 있습니다. 

HubSpot에서 웹훅 구성을 테스트하려면 어떻게 해야 하나요?

POST 또는 GET 웹훅을 설정할 때 테스트를 실행하여 웹훅 응답을 확인할 수 있습니다. 테스트 중에는 타사에 데이터가 전송되고 타사에서 데이터가 가져오더라도 HubSpot의 기존 레코드에는 영향을 미치지 않습니다. 인증에 API 키를 사용하는 경우, 테스트 요청에는 API 키가 표시되지 않습니다.

웹훅 테스트를 마친 후, 워크플로우의 후속 단계에서 입력값으로 사용할 필드를 선택할 수 있습니다. 모든 응답에서 제공되는 출력 필드만 선택하십시오. 출력 필드가 후속 액션에서 사용되지만 응답에 포함되어 있지 않은 경우, 해당 액션은 실패합니다.

1. HubSpot 계정에서 더 보기를 클릭한 다음 자동화 > 워크플로로 이동하세요. 더 보기가 계정에 표시되지 않으면 바로 자동화 > 워크플로로 이동하세요.
2. 워크플로우 이름을 클릭합니다.
3. 워크플로 편집기에서 ‘웹훅 전송’ 액션을 클릭합니다.
4. 왼쪽 패널에서 '액션 테스트'를 클릭하여 해당 섹션을 펼치세요.
5. POST 요청을 테스트하는 경우, 웹훅 테스트 설정은 웹훅 액션에서 '요청 본문 사용자 지정 '을 선택했는지, 아니면 '모든 [객체] 속성 포함'을 선택했는지에 따라 달라집니다.
   • '요청 본문 사용자 지정'을 선택한 경우, 테스트에 사용할 속성 테스트 값을 입력합니다.
   • '모든 [객체] 속성 포함'을 선택한 경우, [객체] 드롭다운 메뉴를 클릭한 다음 테스트에 사용할 레코드를 선택하십시오.
6. '테스트'를 클릭합니다.
7. 웹훅 세부 정보를 확인하려면 '응답' 또는 '요청' 탭을 선택하십시오. 각 탭에서 '모두 열기'를 클릭하여 모든 섹션을 펼치거나, '모두 접기'를 클릭하여 모든 섹션을 접을 수 있습니다.
   • '응답' 탭에서 '헤더:' 또는 '본문: '을 클릭하여 각 섹션을 펼치십시오 .
   • 'Request' 탭에서 'httpHeaders:'를 클릭하여 해당 섹션을 펼치십시오 .
     
     

외부 도구를 사용하여 웹훅을 테스트하려면 어떻게 해야 하나요?

웹훅 액션이 포함된 워크플로를 생성한 후, 더미 웹훅 URL을 사용하여 간단한 테스트를 실행할 수 있습니다:

1. 브라우저에서 https://webhook.site 로 이동하여 고유한 URL을 복사합니다.
2. 웹훅 액션의 ‘웹훅 URL’ 필드에 해당 URL을 붙여넣으세요.
3. 워크플로가 활성화된 후에는 테스트용 연락처를 수동으로 등록할 수 있습니다.
4. 외부에서 웹훅을 테스트할 때:
   • POST 요청이 포함된 웹훅 액션이 트리거되면, 양식 제출 내용, 목록 멤버십, 모든 연락처 속성 값을 포함한 연락처에 대한 모든 정보가 담긴 JSON 응답 본문이 웹훅으로 전송됩니다. 수신 시스템은 이 JSON 데이터를 파싱하여 자체 애플리케이션에 활용할 수 있습니다.
   • GET 요청이 포함된 웹훅 액션이 트리거되면, 추가 쿼리 매개변수가 적용되지 않은 한 일반적인 GET 요청이 전송됩니다.

참고: 과거 속성 값은 연락처 기반 워크플로우에서만 반환됩니다. 다른 모든 워크플로우 유형에서 사용되는 웹훅은 가장 최근의 값만 반환합니다.

웹훅

요청이 HubSpot에서 온 것임을 어떻게 확인할 수 있나요?

'웹훅 트리거' 액션의 '인증' 섹션에서 '요청 서명'을 선택한 경우, HubSpot은 애플리케이션의 앱 시크릿, HTTP 메서드, URI 및 구문 분석되지 않은 본문을 연결한 값의 SHA-256 해시를 포함하는 X-HubSpot-Signature 헤더를 웹훅에 포함시킵니다. 자세한 내용은 개발자 문서를 참조하세요 .

URL로 수신된 요청이 HubSpot에서 온 것인지 확인하려면:

• 개발자 계정이 있어야 합니다. 계정이 없는 경우 개발자 계정에 가입하세요.
• 앱을 소유하고 있어야 합니다. 앱이 없는 경우, 앱 생성 방법을 확인하세요.
• 서명의 해시 값을 확인하십시오.

웹훅을 사용하여 워크플로를 자동으로 시작하려면 어떻게 해야 하나요?

웹훅을 사용하여 워크플로를 트리거할 수 있습니다. 타사 앱에서 데이터가 변경되면 워크플로가 트리거될 수 있습니다. 웹훅을 통한 워크플로 트리거에 대해 자세히 알아보세요.

다른 워크플로 액션에서 웹훅 응답 데이터를 사용하려면 어떻게 해야 하나요?

계정에 연결된 웹훅의 데이터는 데이터 패널의 특정 액션에 사용할 수 있습니다.

연결된 웹훅의 데이터를 사용하려면:

1. HubSpot 계정에서 더 보기를 클릭한 다음 자동화 > 워크플로로 이동하세요. 더 보기가 계정에 표시되지 않으면 바로 자동화 > 워크플로로 이동하세요.
2. 워크플로우 이름을 클릭하세요.
3. + 아이콘을 클릭하여 액션을 추가하세요.
4. 왼쪽 패널에서 데이터 패널을 사용하는 액션을 선택합니다.
5. 데이터 패널의 '액션 데이터' 섹션에서 '웹훅 전송' 액션을 선택하세요. 그러면 연결된 웹훅의 속성을 사용할 수 있습니다.
    

웹훅이 실패하면 어떻게 되나요?

HubSpot은 실패한 웹훅에 대해 실패 후 1분이 지난 시점부터 최대 3일 동안 재시도합니다. 이후 실패 시에는 재시도 간격이 점차 늘어나며, 시도 간 최대 간격은 8시간입니다.

워크플로는 4XX 시리즈 응답 상태 코드를 수신한 후에는 재시도하지 않습니다. 단, 429 속도 제한 오류는 예외입니다. 워크플로는 429 응답을 수신한 후 자동으로 재시도하며, 'Retry-After' 헤더가 있는 경우 이를 따릅니다. 'Retry-After'는 밀리초 단위로 기록됩니다. 특정 오류 코드 예외에 대한 자세한 내용은 HubSpot 개발자 문서에서 확인하세요.