Webhooks for Threads

Webhooks for Threads allow you to receive real-time notifications for the subscribed topics and fields.

Receive Live Webhook Notifications

To receive live webhook notifications, the following conditions must be satisfied:

• Your app must have Threads webhooks added as a sub-use case and appropriate fields subscribed to in the App Dashboard.
• For non-tech providers, the apps must be in Live Mode.
• For tech providers, the apps must have permissions with an Advanced Access level. You can request Advanced Access for permissions as shown here:
  
  

  

  If the app permissions don't have an access level of Advanced Access, the app won't receive webhook notifications.
  
  
• The app user must have granted your app appropriate permissions (i.e., threads_basic, threads_read_replies for reply webhooks).
• The business connected to the app must be verified.
• The owner of the media object upon which the webhook event occurs must not have set their account to private.

Limitations

• Apps don't receive webhook notifications if the media where the reply appears was created by a private account.
• Your app must have successfully completed App Review (Advanced Access) to receive webhooks notifications for the replies webhooks field.

Step 0: [Optional] Use the sample app to test your integration

Download the webhooks sample app to test your integration.

Step 1: Add the webhooks sub-use case to the main Threads API use case

Under Use Cases > Customize > Settings, add the Get real-time notifications with Threads Webhooks sub-use case.

Step 2: Create an endpoint and configure Threads webhooks

Create an endpoint that accepts and processes webhooks. To add the configuration:

1. Select the desired topic, and click Subscribe to this object.
2. Set the callback URL and token.

The token here is passed to your server defined in the callback URL to allow verification that the call originates from Meta servers.

Webhook Topics

Moderate topic fields

Interaction topic fields

Common Uses

Real-time reply notifications

If you subscribe to the replies field, we send your endpoint a webhook notification containing the reply object.

Sample replies payload

{
    "app_id": "123456",
    "topic": "moderate",
    "target_id": "78901",
    "time": 1723226877,
    "subscription_id": "234567",
    "has_uid_field": false,
    "values": {
        "value": {
            "id": "8901234",
            "username": "test_username",
            "text": "Reply",
            "media_type": "TEXT_POST",
            "permalink": "https:\/\/www.threads.net\/@test_username\/post\/Pp",
            "replied_to": {
                "id": "567890"
            },
           "root_post": {
               "id": "123456",
               "owner_id": "123456",
               "username": "test_username_2"
           },
            "shortcode": "Pp",
            "timestamp": "2024-08-07T10:33:16+0000"
        },
        "field": "replies"
    }
}

Real-time mention notifications

If you subscribe to the mentions field, we send your endpoint a webhook notification containing the media object in which the user is mentioned.

Sample mentions payload

{
    "app_id": "123456",
    "topic": "interaction",
    "target_id": "78901",
    "time": 1723226877,
    "subscription_id": "234567",
    "has_uid_field": false,
    "values": {
        "value": {
            "id": "8901234",
            "alt_text": "test alt text",
            "gif_url": "https://media2.giphy.com/media/v1.Y2lkPTA1NzQyMTNjd2R0MXcybjZ6bDNyam9qaXJsN3RicnVncnFsanJ2dGk3eDJiejRmbyZlcD12MV9naWZzX2dpZklkJmN0PWc/3o85xEFRBYvAnamJnG/200.gif",
            "has_replies": true,
            "is_quote_post": false,
            "is_reply": false,
            "link_attachment_url": "https://developers.facebook.com/docs/threads/webhooks/",
            "media_product_type": "THREADS",
            "media_type": "TEXT_POST",
            "media_url": "TEXT_POST",
            "id": "8901234",		
            "permalink": "https:\/\/www.threads.net\/@test_username\/post\/Pp",
            "root_post": {
               "id": "8901234",
               "owner_id": "78901",
               "username": "test_username"
            },
            "shortcode": "Pp",
            "text": "Reply",
            "timestamp": "2024-08-07T10:33:16+0000"
            "username": "test_username",
        },
        "field": "mentions"
    }
}

Note: Additional fields not listed in this sample response that are returned when applicable include: media_url, poll_attachment, quoted_post, replied_to, reposted_post, root_post, and thumbnail_url.