Webhooks - Documentation - Meta for Developers

Overview

Webhooks enable custom integration apps to subscribe to events in Workplace and receive updates in real time. When a change occurs in Workplace, an HTTPS POST request is sent to a callback URL for each custom integration app that's subscribed to the relevant webhook topic.

This makes apps more efficient, as they know exactly when a change has happened and don't need to rely on continuous or even periodic Graph API requests to get the latest content.

Webhook support for Workplace is provided by the same framework that powers Webhooks for Facebook.

Subscribing to Webhook Topics

The Edit Custom Integration dialog provides tabs for each of the webhook topics available to apps on Workplace.

The Webhooks tab in the Edit Custom Integration dialog

To add a new webhook subscription on a given topic, provide a callback URL and a verify token, then select the subscription fields you need for the functionality your app will provide.

You can only subscribe one URL per webhook topic, but you may use the same URL for multiple topics.

Handling Verification Requests

When you add a new subscription, or modify an existing one, Facebook servers will make a GET request to your callback URL in order to verify the validity of the callback server.

A query string will be appended to this URL with the following parameters:

hub.mode - The string "subscribe" is passed in this parameter
hub.challenge - A random string
hub.verify_token - The verify_token value you specified when you created the subscription

When receiving a HTTP GET request on your callback URL, you can use verify_token parameter to validate that the request comes from a Facebook server.

Webhook Security

All webhook calls to developer-defined callback URLs are made via HTTPS, ensuring transport-level security for webhook payloads.

To provide additional security a HTTP header X-Hub-Signature-256 is included in each POST payload, which you should use to verify that the payload came from a Facebook server.

For full details of this behavior, refer to the Facebook Webhook Framework documentation.

Webhook Topics

Activity on Workplace is grouped into topics. Each topic has a number of fields which map to events on a given topic. Apps can subscribe for webhook updates on each topic, and for specific fields within each topic.

Workplace currently provides webhooks for the following topics and groups:

Page

More information available in the Page Topic Reference Docs.

Subscription Field	Behavior
`mention`	Triggered when a custom integration page (bot) is mentioned in a group.
`messages`	Triggered when a custom integration page (bot) is messaged in Work Chat.
`message_deliveries`	Triggered when a message sent by a custom integration page (bot) is delivered.
`messaging_postbacks`	Triggered when a postback button is pressed in Work Chat.
`message_reads`	Triggered when a message from a custom integration page (bot) is read by the recipient.

Group

More information available in the Group Topic Reference Docs.

Subscription Field	Behavior
`posts`	Triggered when a post is added, updated or deleted in a group.
`comments`	Triggered each time a new comment is added, updated or deleted on a post in a group.
`membership`	Triggered when a group's membership changes.

User

More information available in the User Topic Reference Docs.

Subscription Field	Behavior
`status`	Triggered when a user posts or edits a status update on their own profile.
`events`	Triggered each time a user creates, accepts or declines an event.
`message_sends`	Triggered each time a user sends a Workplace Chat message.

Link

More information available in the Authenticated Previews Docs.

Subscription Field	Behavior
`preview`	Triggered when Workplace needs to retrieve information about a URL.
`collection`	Relevant only for apps on the allow list that support hierarchical Post Composer navigation.

Security

More information available in the Security Topic Reference Docs.

`sessions`

Events triggered when a person logs in or out of Workplace.

Event Behavior

Event	Behavior
`log_in`	User has logged in to Workplace with password or SSO, on either www or mobile apps.
`log_out`	User has logged out of Workplace with password or SSO, on either www or mobile apps. Does not include admin-initiated forced log out (See `admin_force_log_out`)

log_in

User has logged in to Workplace with password or SSO, on either www or mobile apps.

log_out

User has logged out of Workplace with password or SSO, on either www or mobile apps.

Does not include admin-initiated forced log out (See admin_force_log_out)

`passwords`

Events triggered when a person changes their password or requests a password reset.

Event	Behavior
`password_change`	A user's password has been changed, as a result of completing password recovery or via their account settings.
`password_reset_request`	A user's password recovery flow has been initiated, and a code has been sent to the user's email address.
`password_reset_wrong_code`	A user entered an incorrect password reset recovery code.
`password_reset_success`	A user's password recovery flow has been successfully completed.

`admin_activity`

Events triggered when an admin is added or removed from a Workplace community

Event	Behavior
`admin_set_to_unclaimed`	An admin has set a user's account state to unclaimed, from the admin panel or via the Account Management API.
`admin_force_log_out`	An admin has forced a user log-out across all devices from the Admin Panel.
`admin_deactivate`	An admin has deactivated an account from the Admin Panel or via the Account Management API.
`admin_activate_account`	An admin has activated an account from the Admin Panel or via the Account Management API.
`force_password_reset`	An admin has forced a user to reset their password from the Admin Panel.
`admin_create_account`	An admin has created an account from the Admin Panel.

`two_factor`

Events triggered when a person enables or disables two-factor authentication.

Event	Behavior
`two_factor_enable`	A user has enabled two-factor authentication from the Settings tab. This does not capture when someone confirms a particular phone, but indicates that the feature was enabled.
`two_factor_disable`	A user has disabled two-factor authentication from the Settings tab. This does not capture when someone disables two-factor for a particular phone, but indicates that the feature was disabled.