시작하기

이 문서에서는 앱 사용자가 자신의 사용자 사진에 대한 변경 사항을 게시할 때마다 나에게 알림을 보내도록 Webhooks를 설정하는 방법을 설명합니다. 이 Webhooks를 설정하는 방법을 이해하면 모든 Webhooks를 설정하는 방법을 알게 될 것입니다.

어떠한 Webhooks를 설정하든 다음과 같은 단계를 따라야 합니다.

1. HTTPS 요청을 처리할 수 있는 안전한 서버에서 엔드포인트를 생성합니다.
2. 앱의 앱 대시보드에서 Webhooks 제품을 구성합니다.

이러한 단계는 아래에 자세히 설명되어 있습니다.

엔드포인트 만들기

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

아래 섹션에서는 각 유형의 요청에 포함되는 항목과 이에 대한 응답 방법을 설명합니다. 또는 이러한 요청을 처리하도록 이미 구성되어 있는 샘플 앱을 사용할 수 있습니다.

인증 요청

앱 대시보드에서 Webhooks 제품을 구성할 때마다 엔드포인트 URL에 GET 요청이 전송됩니다. 인증 요청에는 엔드포인트 URL의 끝에 추가된 다음과 같은 쿼리 문자열 매개변수가 포함됩니다. 이는 다음과 같이 표시됩니다.

샘플 인증 요청

GET https://www.your-clever-domain-name.com/Webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock

참고:PHP는 매개변수 이름의 점(.)을 밑줄(_)로 변환합니다.

인증 요청 검증하기

엔드포인트에서 인증 요청을 받을 때마다 다음과 같이 해야 합니다.

• hub.verify_token 값이 앱 대시보드에서 Webhooks 제품을 구성할 때 인증 토큰 필드에서 설정한 문자열과 일치하는지 확인합니다(아직 이 토큰 문자열을 설정하지 않았음).
• hub.challenge 값을 사용하여 응답합니다.

앱 대시보드에 있고 Webhooks 제품을 구성 중인 경우(따라서 인증 요청을 트리거 중인 경우) 대시보드에 엔드포인트가 요청을 올바르게 검증했는지 표시됩니다. 그래프 API의 /app/subscriptions 엔드포인트를 사용하여 Webhooks 제품을 구성하는 경우 API가 응답으로 성공 또는 실패를 표시합니다.

이벤트 알림

Webhooks 제품을 구성할 때는 object 유형에서 특정 fields를 구독합니다(예: user 개체의 photos 필드). 이러한 필드 중 하나에 변경 사항이 있을 때마다 해당 변경 사항을 설명하는 JSON 페이로드가 포함된 POST 요청이 엔드포인트에 전송됩니다.

예를 들어 user 개체의 photos 필드를 구독하는데 앱 사용자 중 한 명이 사진을 게시했을 경우 다음과 같은 POST 요청이 전송됩니다.

POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" } 

페이로드 콘텐츠

페이로드에는 변경 사항을 설명하는 개체가 포함됩니다. Webhooks 제품을 구성할 때 페이로드에 변경된 필드의 이름만 포함해야 할지, 페이로드에 새로운 값도 포함해야 할지 나타낼 수 있습니다.

모든 페이로드는 JSON 형식으로 되어 있으므로 일반 JSON 구문 분석 메서드나 패키지로 페이로드를 구문 분석할 수 있습니다.

대부분의 페이로드에는 다음과 같은 공통 속성이 포함되지만 각 페이로드의 콘텐츠와 구조는 구독하는 개체 필드에 따라 달라집니다. 어느 필드가 포함되는지 확인하려면 각 개체의 참고 문서를 확인하세요.

페이로드 검증하기

Facebook에서 SHA256 서명으로 모든 이벤트 알림 페이로드에 서명하고 요청의 X-Hub-Signature-256 헤더에 있는 서명을 포함합니다(앞에 sha256=을 붙임). 페이로드 검증이 필수는 아니지만 권장합니다.

페이로드를 검증하는 방법은 다음과 같습니다.

1. 페이로드와 앱의 앱 시크릿 코드를 사용하여 SHA256 서명을 생성합니다.
2. X-Hub-Signature-256 헤더의 서명(sha256= 이후 전체)과 자신의 서명을 비교합니다. 서명이 일치하면 페이로드는 진짜입니다.

이벤트 알림에 응답하기

엔드포인트는 200 OK HTTPS로 모든 이벤트 알림에 응답해야 합니다.

빈도

이벤트 알림은 최대 1,000개의 업데이트로 일괄 집계 및 전송됩니다. 그러나 일괄 처리가 보장되지는 않으므로 각각의 Webhooks를 개별적으로 처리하도록 서버를 조정해야 합니다.

서버로 보낸 업데이트가 실패하는 경우 Facebook은 즉시 다시 시도하고 이후 36시간 동안 빈도를 줄이면서 몇 차례 더 시도합니다. 이러한 경우 서버에서 중복 제거를 처리해야 합니다. 확인하지 않은 응답은 36시간 후에 삭제됩니다.

참고: Messenger 이벤트 알림을 전송하는 빈도는 다릅니다. 자세한 내용은 Messenger 플랫폼 Webhooks 문서를 참조하세요.

Webhooks 제품 구성하기

엔드포인트 또는 샘플 앱이 준비되면 앱의 앱 대시보드를 사용하여 Webhooks 제품을 추가하고 구성합니다. Instagram을 제외한 모든 Webhooks에 대해 /{app-id}/subscriptions 엔드포인트를 사용하여 프로그래밍 방식으로 구성할 수도 있습니다.

이 예시에서는 대시보드를 사용하여 앱 사용자의 사진 변경 사항을 구독하는 Webhooks를 구성할 것입니다.

1. 앱 대시보드에서 제품 > Webhooks로 이동하고 드롭다운 메뉴에서 사용자를 선택한 다음 이 개체 구독을 클릭합니다.
   

   사용자 개체 선택

2. 콜백 URL 필드에 엔드포인트의 URL을 입력하고 확인 토큰 필드에 문자열을 입력합니다. 이 문자열은 모든 인증 요청에 포함됩니다. 샘플 앱 중 하나를 사용하는 경우 이는 앱의 TOKEN 구성 변수에 사용한 것과 동일한 문자열이어야 합니다.

   이벤트 알림 페이로드에 변경된 필드의 이름과 해당 필드의 새로운 값을 포함하려면 값 포함을 예로 설정하세요.
   

   엔드포인트 URL 및 인증 토큰 문자열 입력

3. 확인 및 저장을 클릭하면 검증해야 하는 인증 요청이 엔드포인트로 전송됩니다. 엔드포인트가 요청을 성공적으로 검증하면 다음과 같은 내용이 표시됩니다.

   

   검증 성공

4. 마지막 단계는 개별 필드를 구독하는 것입니다. photos 필드를 구독하고 테스트 이벤트 알림을 전송합니다.

   

   사용자 개체에서 사진 필드 구독

   엔드포인트가 올바르게 설정되면 페이로드를 검증하고 검증 성공 시 실행하도록 설정된 코드를 실행합니다. 샘플 앱을 사용 중인 경우 웹 브라우저에서 앱의 URL을 읽어들이세요. 그러면 페이로드 콘텐츠가 다음과 같이 표시됩니다.

   

   테스트 알림 페이로드를 표시하는 샘플 앱

다음 단계

Webhooks를 설정하는 방법을 살펴보았으므로, 이제 특정 제품을 위한 Webhooks를 설정할 때 필요한 추가 단계를 설명하는 다른 문서를 참조할 수 있습니다.

• 광고 계정용 Webhooks
• 인증서 투명성을 위한 Webhooks
• Instagram용 Webhooks
• 잠재 고객용 Webhooks
• Messenger용 Webhooks
• 페이지용 Webhooks
• 결제용 Webhooks
• WhatsApp용 Webhooks