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.
The Edit Custom Integration dialog provides tabs for each of the webhook topics available to apps on Workplace.
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.
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
verify_tokenvalue 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.
All webhook calls to developer-defined callback URLs are made via
HTTPS, ensuring transport-level security for webhook payloads.
To provide additional security a
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.
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:
More information available in the Page Topic Reference Docs.
Triggered when a custom integration page (bot) is mentioned in a group.
Triggered when a custom integration page (bot) is messaged in Work Chat.
Triggered when a message sent by a custom integration page (bot) is delivered.
Triggered when a postback button is pressed in Work Chat.
Triggered when a message from a custom integration page (bot) is read by the recipient.
More information available in the Group Topic Reference Docs.
Triggered when a post is added, updated or deleted in a group.
Triggered each time a new comment is added, updated or deleted on a post in a group.
Triggered when a group's membership changes.
More information available in the User Topic Reference Docs.
Triggered when a user posts or edits a status update on their own profile.
Triggered each time a user creates, accepts or declines an event.
Triggered each time a user sends a Workplace Chat message.
More information available in the Authenticated Previews Docs.
Triggered when Workplace needs to retrieve information about a URL.
Relevant only for apps on the allow list that support hierarchical Post Composer navigation.
More information available in the Security Topic Reference Docs.
Events triggered when a person logs in or out of Workplace.
User has logged in to Workplace with password or SSO, on either www or mobile apps.
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
Events triggered when a person changes their password or requests a password reset.
A user's password has been changed, as a result of completing password recovery or via their account settings.
A user's password recovery flow has been initiated, and a code has been sent to the user's email address.
A user entered an incorrect password reset recovery code.
A user's password recovery flow has been successfully completed.
Events triggered when an admin is added or removed from a Workplace community
An admin has set a user's account state to unclaimed, from the admin panel or via the Account Management API.
An admin has forced a user log-out across all devices from the Admin Panel.
An admin has deactivated an account from the Admin Panel or via the Account Management API.
An admin has activated an account from the Admin Panel or via the Account Management API.
An admin has forced a user to reset their password from the Admin Panel.
An admin has created an account from the Admin Panel.
Events triggered when a person enables or disables two-factor authentication.
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.
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.