Webhooks

개요

Webhooks는 맞춤 통합 앱이 Workplace에서 이벤트를 구독하고 실시간으로 업데이트를 받도록 지원합니다. Workplace에서 변화가 발생하면 관련 Webhooks 주제를 구독하는 각 맞춤 통합 앱에 대해 콜백 URL로 HTTPS POST 요청이 전송됩니다.

따라서 변경이 언제 발생했는지 정확히 알게 되고 최신 콘텐츠를 가져오기 위해 연속적이거나 정기적인 그래프 API 요청을 보낼 필요가 없어 앱의 효율성이 향상됩니다.

Workplace에 대한 Webhooks지원은 그래프 API용 Webhooks를 운영하는 것과 동일한 프레임워크에서 제공합니다.

Webhooks 주제 구독

맞춤 통합 수정 대화 상자는 Workplace의 앱에 제공되는 각 Webhooks 주제에 대한 탭을 제공합니다.

맞춤 통합 수정 대화 상자의 Webhooks 섹션

특정 주제에 대해 새로운 Webhooks 구독을 추가하려면 콜백 URL과 인증 토큰을 제공한 다음, 앱에서 제공할 기능에 필요한 구독 필드를 선택합니다.

인증 요청 처리

새로운 구독을 추가하거나 기존 구독을 수정하면 Meta 서버는 콜백 URL에 GET 요청을 보내어 콜백 서버의 유효성을 인증합니다.

쿼리 문자열은 다음 매개변수와 함께 이 URL에 첨부됩니다.

• hub.mode - 이 매개변수에 'subscribe' 문자열이 전달됨
• hub.challenge - 무작위 문자열
• hub.verify_token - 구독을 만들었을 때 지정한 verify_token 값

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

• hub.verify_token 값이 Webhooks를 구성할 때 인증 토큰 필드에서 설정한 문자열과 일치하는지 확인합니다.
• hub.challenge 값을 사용하여 응답합니다.

Webhooks 보안

개발자가 정의한 콜백 URL로 보내는 모든 Webhooks 호출은 HTTPS를 통해 이루어져 Webhooks 페이로드 전송 시 보안을 보장합니다.

추가적인 보안을 제공하기 위해 각 POST 페이로드에 HTTP 헤더 X-Hub-Signature-256을 포함하며, 이는 페이로드가 Meta 서버에서 전송한 것인지 확인하는 데 사용해야 합니다.

이 동작에 대한 자세한 내용은 Webhooks 프레임워크 문서를 참조하세요.

개발자가 정의한 콜백 URL로 보내는 모든 Webhooks 호출은 HTTPS를 통해 이루어져 Webhooks 페이로드 전송 시 보안을 보장합니다.

API 호출을 사용하여 Webhooks 구독

Webhooks 구독을 읽거나 수정하기 위한 API 호출은 일반적인 맞춤 통합 토큰이 아니라 앱 토큰을 사용해서 보내야 합니다. 앱 토큰은 앱 ID, '|' 기호, 앱 시크릿 코드를 연결하여 생성할 수 있습니다.

예를 들면 다음과 같습니다.

현재의 Webhooks 구독 가져오기(앱 토큰 사용)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

새로운 Webhooks 구독 추가(앱 토큰 사용)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

페이지/앱 구독 문제 해결

Webhooks가 예상한 대로 수신되지 않을 경우 페이지와 앱 사이의 구독이 올바르게 설정되었는지 확인하는 것이 좋습니다. 구독은 자동으로 설정되지만 경우에 따라서 설정이 실패할 수도 있습니다. 예를 들어 Webhooks의 전송이 장기간 실패하면 이 구독이 삭제될 수 있습니다. 타사 앱의 경우 구독이 삭제되면 앱 대시보드에 알림이 표시됩니다.

이 구독을 확인하려면 다음 API 호출을 사용합니다.

현재의 앱/페이지 구독 가져오기(페이지 토큰 사용)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

이 구독을 다시 생성하려면 다음 API 호출을 사용합니다.

현재의 앱/페이지 구독 다시 만들기(페이지 토큰 사용)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

Webhooks 주제

Workplace에서 활동은 주제로 그룹화됩니다. 각 주제에는 특정 주제에 대한 이벤트로 매핑되는 여러 개의 필드가 있습니다. 앱은 각 주제에 대한 Webhooks 업데이트와 각 주제 내의 특정 필드를 구독할 수 있습니다.

현재 Workplace에서는 다음 주제와 그룹에 대한 Webhooks를 제공합니다.

페이지

자세한 내용은 페이지 주제 참고 자료를 참조하세요.

그룹

자세한 내용은 그룹 주제 참고 자료를 참조하세요.

사용자

자세한 내용은 사용자 주제 참고 자료를 참조하세요.

보안

자세한 내용은 보안 주제 참고 자료를 참조하세요.

admin_activity

Workplace 커뮤니티에서 관리자가 추가되거나 삭제될 때 트리거되는 이벤트입니다.

compromised_credentials

커뮤니티 내 일부 사용자 계정의 Workplace 비밀번호가 위험한 것으로 예상할 때 트리거되는 이벤트입니다.

files

Workplace 파일 활동 시 트리거되는 이벤트입니다.

groups

사용자가 Workplace 기업 간 협력 그룹(MCG)을 만들거나 해당 그룹에 참여할 때 트리거되는 이벤트입니다.

integrations

관리자가 통합 속성을 만들거나 변경할 때 트리거되는 이벤트입니다.

invites

사용자가 직접 초대를 통해 Workplace에 가입할 때 트리거되는 이벤트입니다.

passwords

사용자가 비밀번호를 변경하거나 비밀번호 재설정을 요청할 때 트리거되는 이벤트입니다.

sessions

사용자가 Workplace에 로그인하거나 로그아웃할 때 트리거되는 이벤트입니다.

two_factor

사용자가 2단계 인증을 활성화하거나 비활성화할 때 트리거되는 이벤트입니다.

reseller_events

리셀러와 관련된 이벤트입니다.

링크

자세한 내용은 링크 주제 참고 자료를 참조하세요.

지식 라이브러리

자세한 내용은 지식 라이브러리 카테고리 그래프 API 문서를 참조하세요.