Webhooks - 문서 - Meta for Developers

개요

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

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

Workplace에 대한 Webhooks는 Facebook용 Webhooks를 운영하는 것과 동일한 프레임워크에서 지원합니다.

Webhooks 주제 구독

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

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

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

Webhooks 주제당 URL 1개만 구독할 수 있지만 여러 주제에 동일한 URL을 사용할 수 있습니다.

인증 요청 처리

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

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

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

콜백 URL에 대한 HTTP GET 요청을 수신하면 verify_token 매개변수를 사용하여 Facebook 서버에서 보낸 요청인지 검증할 수 있습니다.

Webhooks 보안

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

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

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

Webhooks 주제

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

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

페이지

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

구독 필드	동작
`mention`	맞춤 통합 페이지(봇)가 그룹에서 언급되었을 때 트리거됩니다.
`messages`	맞춤 통합 페이지(봇)가 Work Chat에서 메시지를 받았을 때 트리거됩니다.
`message_deliveries`	맞춤 통합 페이지(봇)가 보낸 메시지가 전달되었을 때 트리거됩니다.
`messaging_postbacks`	Work Chat에서 포스트백 버튼이 눌렸을 때 트리거됩니다.
`message_reads`	맞춤 통합 페이지(봇)가 보낸 메시지를 받는 사람이 읽었을 때 트리거됩니다.

그룹

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

구독 필드	동작
`posts`	그룹에서 게시물이 추가, 업데이트 또는 삭제되었을 때 트리거됩니다.
`comments`	그룹 내 게시물에서 새로운 댓글이 추가, 업데이트 또는 삭제될 때마다 트리거됩니다.
`membership`	그룹의 멤버 현황이 변경될 때 트리거됩니다.

사용자

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

구독 필드	동작
`status`	사용자가 프로필에서 상태 업데이트를 게시하거나 수정할 때 트리거됩니다.
`events`	사용자가 이벤트를 만들거나 수락, 거부할 때마다 트리거됩니다.
`message_sends`	사용자가 Workplace Chat 메시지를 전송할 때마다 트리거됩니다.

링크

자세한 내용은 인증된 미리보기 문서를 참조하세요.

구독 필드	동작
`preview`	Workplace가 URL에 대한 정보를 가져와야 할 때 트리거됩니다.
`collection`	계층적 게시물 작성 도구 탐색을 지원하는 허용 리스트에 등록된 앱과만 관련이 있습니다.

보안

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

`sessions`

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

이벤트 동작

이벤트	동작
`log_in`	사용자가 www 또는 모바일 앱에서 비밀번호나 SSO를 사용하여 Workplace에 로그인했습니다.
`log_out`	사용자가 www 또는 모바일 앱에서 비밀번호나 SSO를 사용하여 Workplace에서 로그아웃했습니다. 관리자가 시작한 강제 로그아웃은 포함하지 않습니다(`admin_force_log_out` 참조).

log_in

사용자가 www 또는 모바일 앱에서 비밀번호나 SSO를 사용하여 Workplace에 로그인했습니다.

log_out

사용자가 www 또는 모바일 앱에서 비밀번호나 SSO를 사용하여 Workplace에서 로그아웃했습니다.

관리자가 시작한 강제 로그아웃은 포함하지 않습니다(admin_force_log_out 참조).

`passwords`

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

이벤트	동작
`password_change`	비밀번호 복구 또는 계정 설정을 통해 사용자의 비밀번호가 변경되었습니다.
`password_reset_request`	사용자의 비밀번호 복구 플로가 시작되었고 코드가 사용자 이메일 주소로 전송되었습니다.
`password_reset_wrong_code`	사용자가 잘못된 비밀번호 재설정 복구 코드를 입력했습니다.
`password_reset_success`	사용자의 비밀번호 복구 플로가 완료되었습니다.

`admin_activity`

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

이벤트	동작
`admin_set_to_unclaimed`	관리자가 관리자 패널이나 계정 관리 API를 통해 사용자의 계정 상태를 클레임되지 않음으로 설정했습니다.
`admin_force_log_out`	관리자가 관리자 패널에서 사용자를 모든 기기로부터 강제 로그아웃했습니다.
`admin_deactivate`	관리자가 관리자 패널이나 계정 관리 API를 통해 계정을 비활성화했습니다.
`admin_activate_account`	관리자가 관리자 패널이나 계정 관리 API를 통해 계정을 활성화했습니다.
`force_password_reset`	관리자가 관리자 패널에서 사용자가 강제로 비밀번호를 재설정하도록 했습니다.
`admin_create_account`	관리자가 관리자 패널에서 계정을 만들었습니다.

`two_factor`

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

이벤트	동작
`two_factor_enable`	사용자가 설정 탭에서 2단계 인증을 활성화했습니다. 이는 누군가가 특정 휴대폰을 인증했는지 여부가 아니라, 해당 기능이 활성화되었다는 의미입니다.
`two_factor_disable`	사용자가 설정 탭에서 2단계 인증을 비활성화했습니다. 사용자가 특정 휴대폰에 대해 2단계 인증을 비활성화했는지 여부가 아니라, 해당 기능이 비활성화되었다는 의미입니다.