Webhooks 설정

WhatsApp Business 블로그

Node.js를 사용하여 Webhooks 구현

비즈니스가 수신한 메시지와 고객 프로필 업데이트에 대한 알림을 받으려면 Webhooks를 구독하세요.

엔드포인트 만들기

알림을 받기 시작하기 전에 서버에서 알림을 받을 엔드포인트를 만들어야 합니다.

엔드포인트는 인증 요청과 이벤트 알림이라는 두 가지 유형의 HTTPS 요청을 처리할 수 있어야 합니다. 두 요청 모두 HTTPS를 사용하므로, 유효한 TLS 또는 SSL 인증서가 서버에 올바르게 구성되고 설치되어 있어야 합니다. 자체 서명된 인증서는 지원되지 않습니다.

인증 요청과 이벤트 알림에 대해 자세히 알아보기

Webhooks 설정은 WhatsApp Business 앱에 등록된 전화번호에 영향을 미치지 않습니다. WhatsApp Business 플랫폼으로 전화번호를 마이그레이션한 경우에만 WhatsApp Business 앱에서 더 이상 해당 전화번호를 사용할 수 없습니다.

Webhooks 구독하기

Webhooks를 구독하려면 Meta 앱 ID와 권한을 가져와야 합니다. 이를 위해서는 Meta 앱 대시보드로 이동합니다. 여기에서 다음과 같은 작업을 수행합니다.

Meta 앱 대시보드에서 비즈니스 유형 앱 만들기
앱 대시보드에서 Webhooks 제품을 Meta 앱에 추가하기
각 Meta 앱은 항상 엔드포인트를 하나만 구성할 수 있습니다. Webhooks 업데이트를 여러 엔드포인트로 보내야 하는 경우 여러 개의 Meta 앱이 필요합니다.

솔루션 파트너인 경우 다음을 수행해야 할 수 있습니다.

앱 대시보드에서 whatsapp_business_messaging 권한 추가
Meta 앱 검수를 성공적으로 완료 – 이 단계는 시간이 걸리지만 검수 절차를 진행하는 모든 과정에서 테스트를 계속 수행할 수 있습니다.

Webhooks에 대한 이해

트리거 이벤트가 발생할 때마다 WhatsApp Business 플랫폼은 이벤트를 확인하고 이전에 지정한 Webhooks URL로 알림을 전송합니다. 두 가지 유형의 알림을 받을 수 있습니다.

수신된 메시지: 이 알림은 메시지를 수신했을 때 알려줍니다. 이 문서에서는 '인바운드 알림'이라고 지칭하기도 합니다.
메시지 상태 및 가격 알림: 이 알림은 메시지 상태가 변경되었을 때 알려줍니다(예: 메시지를 읽었거나 전달된 경우). 이 문서에서는 '아웃바운드 알림'이라고 지칭하기도 합니다.

모든 Webhooks는 다음과 같은 일반 형식을 사용합니다.

{
  "object": "whatsapp_business_account",
  "entry": [{
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [{
          "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                  "display_phone_number": "PHONE_NUMBER",
                  "phone_number_id": "PHONE_NUMBER_ID"
              },
              # specific Webhooks payload            
          },
          "field": "messages"
        }]
    }]
}

각 필드에 관한 정보는 구성 요소를 참조하세요.

클라우드 API에서 지원되지 않는 메시지를 수신할 경우 알 수 없는 메시지 Webhooks를 받습니다.

페이로드 크기

Webhooks 페이로드는 30MB 미만이어야 합니다.

샘플 앱 엔드포인트

Webhooks를 테스트할 샘플 앱 엔드포인트를 만듭니다.

Webhooks 전달 실패

엔드포인트로 Webhooks 요청을 보냈는데 서버에서 200이 아닌 다른 HTTP 상태 코드로 응답하는 경우 또는 그 외의 다른 이유로 Webhooks를 전달할 수 없는 경우, 최대 7일 동안 요청이 성공할 때까지 빈도를 낮추면서 계속 전달을 시도합니다.

WhatsApp Business 계정에 대해 Webhooks(및 적절한 필드)를 구독한 모든 앱에 재시도 요청이 전송됩니다. 이로 인해 Webhooks 알림에 중복이 있을 수 있습니다.

IP 주소

터미널에서 다음 명령을 실행하여 Webhooks 서버의 IP 주소를 가져올 수 있습니다.

whois -h whois.radb.net — '-i origin AS32934' | grep ^route | awk '{print $2}' | sort

이러한 IP 주소는 정기적으로 변경되므로 WhatsApp 서버를 허용 리스트에 추가할 경우 이 리스트를 수시로 다시 생성하고 이에 따라 허용 리스트를 업데이트하는 것이 좋습니다.

다음 단계

Webhooks 알림에서 받을 수 있는 정보에 대해 자세히 알아보세요.

WhatsApp Business 플랫폼 | 클라우드 API | Business Management API