Webhooks

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 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 FieldBehavior

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 FieldBehavior

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 FieldBehavior

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.

Security

More information available in the Security Topic Reference Docs.

sessions

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

EventBehavior

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.

EventBehavior

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

EventBehavior

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.

EventBehavior

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.

invites

Events triggered when a person joins Workplace via self-invite.

files

Events triggered when Workplace detects malware in a file upload.

groups

Events triggered when a person creates or joins a Workplace Multi-Company Group.

integrations

Events triggered when an admin creates or changes an integration properties.