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.

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:

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.

Groups

More information available in the Group Topic Reference Docs.

User

More information available in the User Topic Reference Docs.

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

compromised_credentials

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

files

Events triggered upon Workplace file activity.

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.

invites

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

passwords

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

sessions

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

two_factor

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

reseller_events

Events related to reseller.

Links

More information available in the Link Topic Reference Docs

Knowledge Library

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