웹훅 캠페인 생성

웹훅 캠페인을 생성하거나 멀티채널 캠페인에 웹훅을 포함하면 다른 시스템 및 애플리케이션에 실시간 정보를 제공하여 앱 외부 동작을 트리거할 수 있습니다.

웹훅을 사용하여 Salesforce나 Marketo와 같은 시스템 또는 백엔드 시스템에 정보를 전송할 수 있습니다. 예를 들어, 고객이 커스텀 이벤트를 특정 횟수만큼 수행한 후 프로모션으로 고객 계정에 크레딧을 적립할 수 있습니다.

팁

웹훅이 무엇이며 Braze에서 어떻게 사용할 수 있는지 자세히 알아보려면 계속하기 전에 웹훅을 확인하세요.

1단계: 메시지를 작성할 위치 선택하기

메시지를 Campaign으로 보낼지 Canvas로 보낼지 고민되시나요? Campaigns는 타겟팅된 단일 메시징 캠페인에 적합하고, Canvases는 여러 단계로 구성된 사용자 여정에 적합합니다.

• campaign
• canvas

단계:

1. 메시징 > Campaigns로 이동한 다음 Campaign 생성을 선택합니다.
2. 웹훅을 선택하거나, 여러 채널을 타겟팅하는 Campaign의 경우 멀티채널을 선택합니다.
3. Campaign 이름은 명확하고 의미 있게 지정합니다.
4. (선택 사항) 이 Campaign의 사용 방식을 설명하는 설명을 추가합니다.
5. 필요에 따라 팀과 태그를 추가합니다.
   • 태그를 사용하면 Campaign을 더 쉽게 찾고 보고서를 작성할 수 있습니다. 예를 들어 보고서 빌더를 사용할 때 특정 태그로 필터링할 수 있습니다.
6. Campaign에 필요한 만큼 배리언트를 추가하고 이름을 지정합니다. 추가한 각 배리언트마다 다른 웹훅 템플릿을 선택할 수 있습니다. 이 주제에 대한 자세한 내용은 다변량 및 A/B 테스트를 참조하세요.

팁

Campaign의 모든 메시지가 비슷하거나 동일한 콘텐츠를 담을 예정이라면, 배리언트를 추가하기 전에 먼저 메시지를 작성하세요. 그런 다음 배리언트 추가 드롭다운에서 배리언트에서 복사를 선택할 수 있습니다.

단계:

1. Canvas 작성기를 사용하여 Canvas를 생성합니다.
2. Canvas를 설정한 후 Canvas 빌더에서 단계를 추가합니다. 단계에 명확하고 의미 있는 이름을 지정합니다.
3. 단계 스케줄을 선택하고 필요에 따라 지연을 지정합니다.
4. 필요에 따라 이 단계의 오디언스를 필터링합니다. Segments를 지정하고 추가 필터를 적용하여 이 단계의 수신자를 더 세밀하게 조정할 수 있습니다. 오디언스 옵션은 지연 후 메시지가 전송되는 시점에 확인됩니다.
5. 진행 동작을 선택합니다.
6. 메시지와 함께 연결하려는 다른 메시징 채널을 선택합니다.

2단계: 웹훅 빌드하기

새 웹훅을 만들거나, 기존 템플릿을 사용하거나, Braze에서 제공하는 기존 템플릿 중 하나를 사용할 수 있습니다. 그런 다음 편집기의 작성 탭에서 웹훅을 빌드합니다.

작성 탭은 다음 필드로 구성됩니다.

• 언어
• 웹훅 URL
• HTTP 메서드
• 요청 본문

언어

다국어 메시지를 사용하면 여러 시장의 사용자에게 하나의 웹훅을 보낼 수 있습니다. 번역은 요청 본문과 웹훅 URL에서 지원됩니다.

웹훅을 현지화하려면 다음 단계를 따르세요.

1. 워크스페이스에서 지원하려는 로캘을 만듭니다.
2. 작성 탭에서 번역하려는 텍스트만 번역 태그로 감쌉니다. 예를 들면 {% translation greeting %}Hello!{% endtranslation %}와 같습니다.
3. 언어 관리를 선택하고 로캘을 고른 다음, CSV를 업로드하거나 번역 API를 사용하여 번역을 추가합니다.
4. 사용자로 미리보기 드롭다운에서 다국어 사용자를 선택하여 보내기 전에 각 로캘을 미리 확인합니다.

중요

사람이 읽을 수 있는 값만 번역 태그로 감싸세요. JSON 키, 괄호, 쉼표 또는 기타 구조는 절대 감싸지 마세요. 번역자가 특수 문자를 변경하거나 제거할 수 있으며, 이로 인해 엔드포인트가 거부하는 잘못된 형식의 요청 본문이 생성될 수 있습니다.

JSON 키-값 페어로 빌드한 요청 본문의 경우 값에만 태그를 지정합니다.

1
2
3

{
  "message_body": "{% translation order_ready %}Your order just arrived!{% endtranslation %}"
}

URL 현지화하기

시장별로 엔드포인트가 다른 경우 URL의 일부를 번역 태그로 감쌀 수 있습니다. 프로토콜(https://)은 태그 밖에 두고, 쿼리 매개변수는 태그 안에 포함하지 마세요. 자세한 내용은 URL 현지화를 참조하세요.

웹훅 템플릿

웹훅 템플릿은 저장된 번역을 지원하므로 템플릿을 한 번 현지화한 뒤 여러 Campaigns 및 캔버스 단계에서 재사용할 수 있습니다. 템플릿에 로캘과 번역을 추가하려면 웹훅 템플릿 편집 권한이 필요합니다. 웹훅 템플릿을 참조하세요.

웹훅 URL

웹훅 URL, 즉 HTTP URL은 엔드포인트를 지정합니다. 엔드포인트는 웹훅에서 캡처한 정보를 보낼 위치입니다.

공급업체에 정보를 보내려는 경우, 공급업체가 API 설명서에서 이 URL을 제공해야 합니다. 자체 시스템으로 정보를 보내는 경우, 개발팀 또는 엔지니어링 팀에 문의하여 올바른 URL을 사용하고 있는지 확인하세요.

Braze는 표준 포트 80(HTTP) 및 443(HTTPS)을 통해 통신하는 URL만 허용합니다.

Liquid 사용하기

Liquid를 사용하여 웹훅 URL을 개인화할 수 있습니다. 경우에 따라 특정 엔드포인트에서는 URL의 일부로 사용자를 식별하거나 사용자별 정보를 제공하도록 요구할 수 있습니다. Liquid를 사용할 때는 URL에 사용하는 각 사용자별 정보에 대해 기본값을 반드시 포함하세요.

HTTP 메서드

사용해야 하는 HTTP 메서드는 정보를 보내는 엔드포인트에 따라 다릅니다. 대부분의 경우 POST를 사용합니다.

요청 본문

요청 본문은 지정한 URL로 전송될 정보입니다. JSON 키-값 페어 또는 원시 텍스트로 웹훅 요청의 본문을 만들 수 있습니다.

JSON 키-값 페어

JSON 키-값 페어를 사용하면 JSON 형식을 기대하는 엔드포인트에 대한 요청을 쉽게 작성할 수 있습니다. 이 옵션은 JSON 요청을 기대하는 엔드포인트에서만 사용할 수 있습니다. 예를 들어 키가 message_body인 경우 해당 값은 Your order just arrived!일 수 있습니다. 키-값 페어를 입력하면 작성기가 요청을 JSON 구문으로 구성하고, JSON 요청의 미리보기가 자동으로 채워집니다.

Liquid를 사용하여 요청에 사용자 속성, 커스텀 속성 또는 이벤트 속성정보를 포함하는 등 키-값 페어를 개인화할 수 있습니다. 예를 들어 요청에 고객의 이름과 이메일을 포함할 수 있습니다. 각 속성에 대해 기본값을 반드시 포함하세요.

원시 텍스트

원시 텍스트 옵션을 사용하면 모든 형식의 본문을 기대하는 엔드포인트에 대한 요청을 유연하게 작성할 수 있습니다. 예를 들어 XML 형식의 요청을 기대하는 엔드포인트에 대한 요청을 작성할 때 이 옵션을 사용할 수 있습니다.

원시 텍스트에서는 개인화와 번역 태그가 모두 지원됩니다.

Content-Type 요청 헤더를 application/x-www-form-url-encoded로 설정한 경우, 요청 본문은 URL 인코딩된 문자열 형식이어야 합니다. 예를 들면 다음과 같습니다.

1

to={{custom_attribute.${example}}}&text=Your+order+just+arrived

3단계: 추가 설정 구성

요청 헤더(선택 사항)

특정 엔드포인트에서는 요청에 헤더를 포함해야 할 수 있습니다. 작성기의 작성 섹션에서 필요한 만큼 헤더를 추가할 수 있습니다.

일반적인 요청 헤더로는 본문에 어떤 유형의 데이터(예: XML 또는 JSON)가 들어 있는지 설명하는 Content-Type 사양과, 공급업체 또는 시스템의 자격 증명을 포함하는 Authorization 헤더가 있습니다.

참고

HTTP 헤더 이름은 RFC 7230, 섹션 3.2(“각 헤더 필드는 대소문자를 구분하지 않는 필드 이름으로 구성됩니다”)에 따라 대소문자를 구분하지 않습니다. 수신 엔드포인트나 중간 서비스(예: CDN)에서 헤더의 대소문자를 변환하더라도 헤더 처리에는 영향을 주지 않으며, Content-Type, content-type, CONTENT-TYPE은 모두 동일하게 처리됩니다.

콘텐츠 유형 사양에는 반드시 Content-Type 키를 사용해야 합니다. 일반적인 값은 application/json 또는 application/x-www-form-urlencoded입니다.

Authorization 헤더에는 반드시 Authorization 키를 사용해야 합니다. 일반적인 값은 Bearer {{YOUR_TOKEN}} 또는 Basic {{YOUR_TOKEN}} 이며, 여기서 YOUR_TOKEN은 공급업체 또는 시스템에서 제공한 자격 증명입니다.

4단계: 메시지 테스트 전송

Campaign을 실시간으로 시작하기 전에 Braze는 웹훅을 테스트하여 요청 형식이 올바른지 확인할 것을 권장합니다.

이렇게 하려면 테스트 탭으로 전환하여 테스트 웹훅을 전송합니다. 무작위 사용자, 특정 사용자(이메일 주소 또는 외부 사용자 ID 입력), 또는 원하는 속성을 지정한 커스텀 사용자로 웹훅을 테스트할 수 있습니다.

테스트 웹훅을 전송하면 응답 메시지가 포함된 대화 상자가 나타납니다. 웹훅 요청이 실패하면 오류 메시지를 참고하여 웹훅 문제를 해결하세요. 다음 예시는 유효하지 않은 웹훅 URL을 사용한 웹훅의 응답을 보여줍니다.

1
2
3
4
5
6
7
8
9

404 Not Found

{
  "error": {
    "message": "Unrecognized request URL. Please see https://lob.com/docs or email us at [email protected].",
    "status_code": 404
  }
}

자세한 내용은 테스트 메시지 보내기를 참조하세요.

5단계: Campaign 또는 Canvas의 나머지 부분 구성하기

• campaign
• canvas

다음으로 Campaign의 나머지 부분을 구성합니다. 웹훅을 구성할 때 도구를 가장 잘 활용하는 방법에 대한 자세한 내용은 다음 섹션을 참조하세요.

전달 스케줄 또는 트리거 선택하기

웹훅은 예약된 시간, 실행 또는 API 트리거를 기반으로 전달할 수 있습니다. 자세한 내용은 Campaign 스케줄 설정하기를 참조하세요.

실행 기반 전달의 경우 Campaign 기간과 방해금지 시간도 설정할 수 있습니다.

이 단계에서는 사용자가 Campaign을 다시 수신할 수 있도록 재자격을 허용하거나 최대 게재빈도 설정 규칙을 활성화하는 등 전달 제어 설정을 지정할 수도 있습니다.

타겟팅할 사용자 선택하기

다음으로 Segment 또는 필터를 선택하여 오디언스 범위를 좁혀 사용자를 타겟팅해야 합니다. 이 단계에서는 Segment에서 더 큰 오디언스를 선택하고, 원하는 경우 필터를 사용해 해당 Segment를 더 좁힐 수 있습니다. 대략적인 Segment 모집단이 어떻게 구성되는지 미리보기가 자동으로 제공됩니다. 정확한 Segment 멤버십은 항상 메시지가 전송되기 전에 계산된다는 점에 유의하세요.

중요

귀하의 메시지는 타겟 오디언스 단계에서 설정한 조건에 이미 부합하는 사용자에게만 전송됩니다. 그 후에도 전달 스케줄 단계에서 정의한 트리거 조건을 충족해야 합니다. 타겟 오디언스를 대기실이라고 생각해 보세요. 다음 동작이 발생할 때 이미 안에 있는 사람들만 앞으로 나아갈 수 있습니다.

전환 이벤트 선택하기

Braze를 사용하면 Campaign을 수신한 후 사용자가 특정 행동, 즉 전환 이벤트를 얼마나 자주 수행하는지 추적할 수 있습니다. 사용자가 지정된 행동을 수행하면 전환으로 집계되는 기간을 최대 30일까지 허용할 수 있습니다.

아직 완료하지 않았다면 Canvas 단계의 나머지 섹션을 완료하세요. 다변량 테스트 및 BrazeAI^TM로 최적화를 포함하여 Canvas의 나머지 부분을 구성하는 방법에 대한 자세한 내용은 Canvas 구성하기를 참조하세요.

6단계: 검토 및 배포

Campaign 또는 Canvas의 마지막 부분까지 구축을 마쳤다면 세부 정보를 검토하고 테스트한 다음 전송하세요!

알아두어야 할 사항

오류, 재시도 로직 및 시간 초과

웹훅은 Braze 서버가 외부 엔드포인트로 요청을 보내는 방식으로 작동하므로 가끔 오류가 발생할 수 있습니다. 가장 흔한 오류로는 구문 오류, 만료된 API 키, 사용량 제한, 예기치 않은 서버 측 문제가 있습니다. 웹훅 Campaign을 보내기 전에 다음을 확인하세요.

• 웹훅에 구문 오류가 없는지 테스트합니다.
• 개인화된 변수에 기본값이 있는지 확인합니다.

웹훅 전송에 실패하면 메시지 활동 로그에 오류 메시지가 기록됩니다. 이 메시지에는 오류 타임스탬프, 앱 이름, 오류 세부 정보가 포함됩니다.

오류 메시지만으로 오류의 원인을 파악하기 어렵다면 사용 중인 API 엔드포인트의 설명서를 확인하세요. 설명서에는 일반적으로 엔드포인트가 사용하는 오류 코드와 각 오류의 일반적인 원인이 설명되어 있습니다.

응답 코드 및 재시도 로직

웹훅 요청이 전송되면 수신 서버는 요청 처리 결과를 나타내는 응답 코드를 반환합니다. 다음 표에는 서버가 보낼 수 있는 다양한 응답, 각 응답이 Campaign 분석에 미치는 영향, 그리고 오류가 발생한 경우 Braze가 Campaign을 다시 전달하려고 시도하는지 여부가 요약되어 있습니다.

참고

Braze는 이 섹션에서 재시도 가능한 상태 코드에 대해 최대 총 5회(최초 요청 1회와 재시도 4회)까지 시도하며, 시도 간 지연 시간은 점점 늘어납니다. Braze가 엔드포인트에 연결할 수 없는 경우 재시도는 최대 24시간 동안 계속될 수 있습니다.

각 웹훅 요청은 시간 초과 전까지 120초가 주어집니다.

Retry-After 및 사용량 제한 응답 헤더는 Braze가 재시도 가능한 시도(예: 408, 429 또는 5XX 이후) 전에 대기하는 시간에 영향을 줄 수 있습니다. 하지만 401과 같이 재시도할 수 없는 응답을 재시도 대상으로 만들지는 않습니다.

참고

웹훅 전송이 분석에서 누락된 것처럼 보이면 해당 Campaign 또는 캔버스 단계의 메시지 활동 로그를 여세요. Braze는 특정 응답(예: 408, 429, 5XX)만 재시도하며, 401 Unauthorized를 포함한 대부분의 다른 4XX 클라이언트 오류는 재시도하지 않습니다. 전체 응답 표는 응답 코드 및 재시도 로직을 참조하세요.

403 Forbidden 및 IP 허용 목록 {#403-forbidden-and-ip-allowlisting} {#403-forbidden-and-ip-allowlisting}

403 Forbidden 응답은 엔드포인트가 요청을 받았지만 거부했다는 의미입니다. 일반적인 원인으로는 유효하지 않거나 누락된 인증, 불충분한 API 권한, 그리고 Braze의 아웃바운드 IP 주소를 차단하는 네트워크 규칙(예: 방화벽 또는 웹 애플리케이션 방화벽)이 있습니다.

웹훅 요청이 계속 403을 반환하는데 인증 헤더가 올바르다면, 웹훅을 수신하는 서버에서 해당 클러스터의 Braze IP를 허용 목록에 추가하세요. IP 허용 목록을 참조하세요. 연결된 콘텐츠 요청도 동일한 아웃바운드 IP를 사용합니다. 연결된 콘텐츠 IP 허용 목록을 참조하세요.

기타 4XX 문제 해결 단계는 웹훅 및 연결된 콘텐츠 요청 문제 해결을 참조하세요.

인증 및 연결된 콘텐츠 자격 증명

아웃바운드 웹훅 HTTP 요청은 엔드포인트 인증을 위해 연결된 콘텐츠 자격 증명(:basic_auth 또는 :auth_credentials)을 첨부하는 기능을 지원하지 않습니다. 대신 웹훅의 요청 헤더를 사용하여 인증을 설정하세요. 전송 시점에 토큰이나 시크릿을 가져오려면 헤더 또는 본문 필드에 {% connected_content %} 태그를 넣어 웹훅이 전송되기 전에 Liquid가 이를 처리하도록 할 수 있습니다.

저장된 웹훅 템플릿 및 Campaign 사용 현황

Braze는 특정 저장된 웹훅 템플릿을 참조하는 모든 Campaign 또는 캔버스 단계를 나열하는 기본 제공 보고서를 제공하지 않습니다. 사용 현황을 감사하려면 동일한 URL과 HTTP 메서드를 사용하는 웹훅 단계를 검토하거나 Braze 지원팀에 문의하세요.

문제 해결 및 추가 오류 세부 정보

특정 웹훅 오류에 대한 자세한 설명, 문제 해결 단계, 해결 가이드는 웹훅 및 연결된 콘텐츠 요청 문제 해결을 참조하세요. 이 문서에서는 비정상 호스트 감지 시스템의 작동 방식과 Braze가 자동 이메일 및 Braze 커런츠의 추가 로깅을 통해 오류 알림을 제공하는 방식에 대한 추가 설명도 확인할 수 있습니다.

IP 허용 목록

Braze에서 웹훅을 보내면 Braze 서버가 고객 또는 타사 서버로 네트워크 요청을 보냅니다. IP 허용 목록을 사용하면 웹훅 요청이 Braze에서 온 것인지 확인할 수 있어 보안을 한층 강화할 수 있습니다.

Braze는 다음 IP에서 웹훅을 보냅니다. 나열된 IP는 허용 목록에 옵트인한 모든 API 키에 자동으로 동적으로 추가됩니다.

중요

Braze 간 웹훅을 만들면서 허용 목록을 사용하는 경우 127.0.0.1을 포함하여 다음 IP를 모두 허용 목록에 추가해야 합니다.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

사용자 삭제

개별 사용자 또는 사용자 Segment를 삭제하려면 오디언스 > 오디언스 관리 > 사용자 삭제로 이동하세요. 대시보드는 대량 Segment 삭제(최대 1,000만 개 프로필)를 지원하고, 7일간의 취소 기간을 제공하며, 공유 REST API 사용량 제한을 소비하지 않습니다. 단계, 제한 사항 및 권한은 사용자 삭제를 참조하세요.

더 작은 배치로 프로그래밍 방식으로 삭제하려면 웹훅 Campaign 대신 /users/delete 엔드포인트를 사용하세요.