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 Graph API.

Subscribing to Webhook Topics

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

The Webhooks section 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, Meta 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

Whenever your endpoint receives a verification request, it must:

  • Verify that the hub.verify_token value matches the string you set in the Verify Token field when you configure the webhook.
  • Respond with the hub.challenge value.

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 Meta server.

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

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

Subscribing to webhooks using an API call

API calls to read or modify webhook subscriptions need to be made using an app token rather than the usual custom integration token. An app token can be generated by concatenating the app id, a '|' symbol and the app secret.

For example:

DataString

App ID

504221332732118

App secret

d76ab3f35f3ff5aa6ffdc8637a660d2ea7

App token:

504221332732118|d76ab3f35f3ff5aa6ffdc8637a660d2ea7

Get current webhook subscriptions (using app token)

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

Add new webhook subscription (using app token)

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}

Troubleshooting Page/App Subscriptions

In cases where webhooks are not being received as expected, it is recommended to check that subscription between the page and the app is set up correctly. This should be set up automatically, but in some cases can fail. For example, if webhook delivery fails for an extended period, this subscription can be removed. For third party apps, this will result in an alert in the app dashboard.

To check this subscription, the following API calls are available:

Get current app/page subscription (using page token)

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

To re-create this subscription, the following API calls are available:

Re-create current app/page subscription (using page token)

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

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.

Groups

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.

membership_requests

Triggered when a user requests group membership.

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. This includes posts on a user's timeline.

events

Triggered each time a user creates, accepts or declines an event.

message_sends

Triggered each time a user sends a Workplace Chat message.

message_unsends

Triggered each time a user removes a Workplace Chat message for everyone in a thread.

timeline_comments

Triggered each time there's a comment on a post in a user's timeline.

Security

More information available in the Security Topic Reference Docs.

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.

compromised_credentials

Events triggered when we suspect that the Workplace passwords of some user accounts in a community may be at risk.

EventBehavior

found_compromised_credentials

Workplace has found compromised credentials.

files

Events triggered upon Workplace file activity.

EventBehavior

group_file_upload

A user has uploaded a file to a group.

group_file_download

A user has downloaded a file from a group.

file_upload_malware_found

An uploaded file was found to contain malware.

groups

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

EventBehavior

mcg_join

A user in the community has joined an MCG.

mcg_create

A user in the community has created an MCG.

integrations

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

EventBehavior

custom_integration_create

An admin has created a custom integration.

custom_integration_edit

An admin has edited a custom integration.

custom_integration_delete

An admin has deleted a custom integration.

custom_integration_token_reset

An admin has generated a new access token for a custom integration.

content_app_install

A user has created a content integration.

content_app_uninstall

A user has uninstalled a content integration.

invites

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

EventBehavior

coworker_invite_sent

A user has invited a coworker to join the community.

self_invite_sent

A user has requested an invite email for themselves.

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.

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)

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.

add_two_factor_phone

A user has added and confirmed a phone used for two factor authentication.

two_factor_code_success

A user has entered a valid two factor code when logging in on the Workplace website or mobile website

two_factor_code_failure

A user has entered an invalid two factor code when logging in on the Workplace website or mobile website

two_factor_code_success_m

A user has entered a valid two factor code when logging in on a Workplace iOS or Android mobile app

two_factor_code_failure_m

A user has entered an invalid two factor code when logging in on a Workplace iOS or Android mobile app

reseller_events

Events related to reseller.

EventBehavior

reseller_user_added

Allows a non-admin user in a reseller company to see reseller console.

reseller_user_removed

Disallows a non-admin user in a reseller company to see reseller console.

reseller_invite_sent

Reseller Invites another company to be linked to them.

reseller_invite_accepted

A company accepts reseller invite to be linked.

reseller_invite_declined

A company declines reseller invite to be linked.

Links

More information available in the Link Topic Reference Docs

EventBehavior

preview

Metadata about the user requesting access to shareable links.

collection

The metadata for a link shared on Workplace to generate a preview.

Knowledge Library

More information available in the Knowledge Library Category Graph API Docs.

Subscription FieldBehavior

categories

Triggered when Knowledge Library content is being added, updated or deleted or when read audience is updated.

comments

Triggered each time a new comment is added, updated or deleted in Knowledge Library.

quicklinks

Triggered when Knowledge Library quick link is being added, updated or deleted.