Gareth Wilson Gareth Wilson

Guide to Threads Webhooks: Features and Best Practices

Published · Updated


Threads webhooks tell your app in real time when someone replies to or mentions one of your users on Threads, and when your users publish or delete posts. If you build social listening, moderation or publishing tools on Meta's Threads API, webhooks replace polling for replies and mentions.

This guide covers how Threads webhooks are set up in the App Dashboard, the verification request and signature they share with other Meta webhooks, the four fields and their payloads, and the conditions that decide whether notifications arrive at all.

What are Threads webhooks?

Threads webhooks are part of the Threads API use case in a Meta app. You add a webhooks sub-use case, subscribe to fields in two topics, and set a callback URL and a verify token. When a subscribed change happens, Meta sends a POST with a JSON notification to the callback URL.

The mechanics come from Meta's shared Graph API webhooks guide, which the Threads page links to. Saving the callback URL triggers a GET verification request that your endpoint must answer with a challenge value. Every notification is then signed with an X-Hub-Signature-256 header: sha256= and the hex HMAC-SHA256 of the payload, keyed with your app secret.

Threads webhook features

FeatureDetails
ConfigurationApp Dashboard: Use Cases > Customize > Settings, add the Threads webhooks sub-use case
Topicsmoderate (replies, delete) and interaction (mentions, publish)
Endpoint verificationGET with hub.mode, hub.verify_token and hub.challenge, answered with the challenge
Signature headerX-Hub-Signature-256 (plus a legacy SHA-1 X-Hub-Signature)
SchemeHMAC-SHA256, hex, prefixed with sha256=
Signed contentThe raw request body only
SecretThe Threads App Secret, not the Meta App Secret
RetriesImmediately, then with decreasing frequency over 36 hours (Meta's guide)
RequirementsLive Mode or Advanced Access, a verified business, user permissions, public media owners

Meta publishes no source IP list for webhooks, and the signature carries no timestamp.

Common events

Threads organises notifications into two topics with two fields each.

FieldTopicSent whenRequired permissions
repliesmoderateSomeone replies to a post owned by the user who installed your appthreads_basic, threads_read_replies
deletemoderateThe authenticated user deletes a postthreads_basic, threads_delete
mentionsinteractionA public post mentions the user who installed your appthreads_basic, threads_manage_mentions
publishinteractionThe authenticated user publishes a post, including repliesthreads_basic

For mentions, threads_read_replies is optional. Without it, the has_replies, is_reply, replied_to and root_post fields are removed from the notification.

Unlike the Graph API's entry[].changes[] envelope, Threads notifications are flat. Here is a publish notification from a live test, with the IDs replaced:

{
  "app_id": "1234567890123456",
  "topic": "interaction",
  "target_id": "12345678901234567",
  "time": 1795003505,
  "subscription_id": "2345678901234567",
  "has_uid_field": false,
  "values": [
    {
      "value": {
        "id": "17951234567890123",
        "permalink": "https://www.threads.com/@test_username/post/AbCdEfGhIjK",
        "media_type": "TEXT_POST",
        "username": "test_username",
        "timestamp": "2026-11-18T12:04:57+0000"
      },
      "field": "publish"
    }
  ]
}

Meta's documentation shows values as a single object, but the live notification wrapped it in an array. Accept both shapes.

  • Each entry's field is the field that changed. Route on it.
  • Each entry's value is the media object: the reply, the mentioning post, or the published or deleted post.
  • app_id is the Threads App ID from App settings > Basic in the App Dashboard.
  • target_id is the media ID for a reply or delete, or the mentioned user's app-scoped ID for a mention.
  • time is when the notification was sent.

Meta's samples for mentions, delete and publish are missing commas, so don't copy them as test fixtures without fixing them.

Setting up Threads webhooks

  1. In the App Dashboard, under Use Cases > Customize > Settings, add the Get real-time notifications with Threads Webhooks sub-use case.
  2. Select a topic and click Subscribe to this object.
  3. Set the callback URL and a verify token. Meta sends the token to your callback URL so you can confirm the request comes from Meta.
  4. Subscribe to the fields you need.

When you save the callback URL, Meta sends a GET request with hub.mode=subscribe, hub.verify_token and hub.challenge as query parameters. Your endpoint should check that the verify token matches and respond with the hub.challenge value.

Notifications only start flowing when the app meets Meta's conditions:

  • Non-tech-provider apps must be in Live Mode. Tech providers need Advanced Access for the permissions, which means completing App Review.
  • The user must have granted your app the permissions for the field.
  • The business connected to the app must be verified.
  • For replies and mentions, the owner of the media must not have a private account. For delete and publish, the owner must be public, or a private account that authenticated to your app.

In our test, an app in Development Mode received no notifications, and the App Dashboard has no test button for Threads webhooks. Publishing the app to Live Mode only needed a privacy policy URL. After that, a Threads tester who granted threads_basic triggered a publish notification by posting.

If you use Hookdeck, create a source with the Threads source type and use its URL as the callback URL. Hookdeck answers Meta's verification request for you by echoing hub.challenge. It doesn't check the verify token, so any token you set in the App Dashboard is accepted. Paste the Threads App Secret into the source's secret field (see the next section), even if the field is labelled App Secret or mentions App settings > Basic.

Securing Threads webhooks

Read X-Hub-Signature-256, check that it starts with sha256=, and take the rest. Compute the hex HMAC-SHA256 of the raw request body with the Threads App Secret as the key, and compare the two in constant time.

Which secret? A Threads app has two: the Meta App Secret under App settings > Basic, and a separate Threads App Secret under Use cases > Customize > Settings in the Threads API use case. Meta's guide only says "your app's App Secret". We tested a live notification and it was signed with the Threads App Secret. The Meta App Secret didn't match.

Meta also sends a legacy X-Hub-Signature header with sha1= and the hex HMAC-SHA1 of the body, keyed with the same secret. Verify the SHA-256 header.

const crypto = require('crypto');
const express = require('express');

function verifyThreadsSignature(rawBody, signatureHeader, appSecret) {
  if (!signatureHeader || !appSecret || !signatureHeader.startsWith('sha256=')) return false;
  const received = Buffer.from(signatureHeader.slice('sha256='.length).toLowerCase(), 'utf8');
  const expected = Buffer.from(
    crypto.createHmac('sha256', appSecret).update(rawBody).digest('hex'),
    'utf8'
  );
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

const app = express();

// Meta's verification request, sent when you save the callback URL.
app.get('/webhooks/threads', (req, res) => {
  if (req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === process.env.THREADS_VERIFY_TOKEN) {
    return res.status(200).send(req.query['hub.challenge']);
  }
  res.sendStatus(403);
});

app.post('/webhooks/threads', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifyThreadsSignature(req.body, req.get('x-hub-signature-256'), process.env.THREADS_APP_SECRET)) {
    return res.sendStatus(401);
  }

  const notification = JSON.parse(req.body.toString('utf8'));
  const changes = [].concat(notification.values); // documented as an object, sent as an array
  // Route on each change.field, then queue the work.
  res.sendStatus(200);
});

The same signature check in Python:

import hashlib
import hmac


def verify_threads_signature(raw_body: bytes, signature_header, app_secret: str) -> bool:
    if not signature_header or not app_secret or not signature_header.startswith("sha256="):
        return False
    received = signature_header[len("sha256="):].lower()
    expected = hmac.new(app_secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received.encode("utf-8"), expected.encode("utf-8"))


# In FastAPI: raw_body = await request.body()
# verify_threads_signature(raw_body, request.headers.get("x-hub-signature-256"),
#                          os.environ["THREADS_APP_SECRET"])

The signature covers only the body. The body's time field isn't a separate signed timestamp, so there is no replay window to check.

Make Threads webhooks production-ready. Hookdeck Event Gateway answers Meta's verification request, verifies the X-Hub-Signature-256 header on every notification, and queues each reply, mention and post event until your service has processed it.

Threads webhook limitations and pain points

Verifying with the wrong secret

The Problem: Every notification fails verification even though the code is right.

Why It Happens: Threads apps have two secrets. Meta's guide says to use the App Secret, and the obvious one under App settings > Basic is the Meta App Secret, but Threads webhooks are signed with the Threads App Secret.

Workarounds:

  • Copy the Threads App Secret from Use cases > Customize > Settings in the Threads API use case.
  • Note next to the code which secret it uses, so a later rotation updates the right one.

How Hookdeck Can Help: Hookdeck marks each request as verified or failed, so a wrong secret on the source shows up on the first notification.

Notifications that never arrive

The Problem: The webhook is configured and verified, but nothing comes through.

Why It Happens: Meta has many preconditions: Live Mode or Advanced Access, a verified business, the right user permissions, and media from public accounts. Replies and mentions on media created by private accounts never produce notifications.

Workarounds:

  • Work through Meta's list of conditions for each field before debugging your endpoint.
  • Test with a public account that has granted all the permissions for the field.

How Hookdeck Can Help: Hookdeck's request log shows whether Meta sent anything at all, which separates a configuration problem from a receiver problem.

Retries stop after 36 hours

The Problem: Notifications from a long outage are gone.

Why It Happens: Meta's guide says failed deliveries are retried immediately and then with decreasing frequency over 36 hours, after which they are dropped.

Workarounds:

  • Return 200 as soon as the request is verified and stored.
  • After a long outage, fetch replies and mentions through the Threads API.

How Hookdeck Can Help: Hookdeck accepts each notification as soon as it arrives, so Meta's retry window isn't spent on your downtime. Hookdeck then delivers to your service with retries you configure.

No event ID

The Problem: A retried notification looks like a new reply.

Why It Happens: The notification has no delivery ID, and Meta retries failed deliveries.

Workarounds:

  • Deduplicate on each entry's field plus value.id, the media ID.

How Hookdeck Can Help: Hookdeck's deduplication can drop repeats based on those body fields.

Best practices

Verify against the raw body

The HMAC covers the body exactly as Meta sent it. Use express.raw({ type: '*/*' }) in Express, await request.text() in Next.js and await request.body() in FastAPI.

Implement both requests

If your own endpoint receives Threads webhooks, it needs a GET handler for verification and a POST handler for notifications. Keep the verify token secret.

Request only the permissions you use

Each field needs specific permissions, and every permission goes through App Review. Subscribe to the fields you need, and add threads_read_replies for mentions only if you use the reply fields.

Acknowledge fast and process asynchronously

Verify, store the notification, return 200, and call the Threads API afterwards. See why to process webhooks asynchronously and our guide to webhook idempotency.

Conclusion

Threads webhooks use Meta's shared mechanism: a hub.challenge verification request when you save the callback URL, then flat JSON notifications signed with X-Hub-Signature-256. Verify the sha256= hex HMAC against the raw body with the Threads App Secret, route on the field of each entry in values, and check Meta's conditions first when notifications don't arrive.

Hookdeck Event Gateway answers the verification request, checks every signature, and keeps each notification until your service has processed it, so an outage doesn't run out Meta's 36-hour retry window.

Get started with Hookdeck for free and handle Threads webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.