# Guide to Threads Webhooks: Features and Best Practices

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

| Feature | Details |
| --- | --- |
| Configuration | App Dashboard: **Use Cases > Customize > Settings**, add the Threads webhooks sub-use case |
| Topics | `moderate` (`replies`, `delete`) and `interaction` (`mentions`, `publish`) |
| Endpoint verification | `GET` with `hub.mode`, `hub.verify_token` and `hub.challenge`, answered with the challenge |
| Signature header | `X-Hub-Signature-256` (plus a legacy SHA-1 `X-Hub-Signature`) |
| Scheme | HMAC-SHA256, hex, prefixed with `sha256=` |
| Signed content | The raw request body only |
| Secret | The Threads App Secret, not the Meta App Secret |
| Retries | Immediately, then with decreasing frequency over 36 hours (Meta's guide) |
| Requirements | Live 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.

| Field | Topic | Sent when | Required permissions |
| --- | --- | --- | --- |
| `replies` | `moderate` | Someone replies to a post owned by the user who installed your app | `threads_basic`, `threads_read_replies` |
| `delete` | `moderate` | The authenticated user deletes a post | `threads_basic`, `threads_delete` |
| `mentions` | `interaction` | A public post mentions the user who installed your app | `threads_basic`, `threads_manage_mentions` |
| `publish` | `interaction` | The authenticated user publishes a post, including replies | `threads_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:

```json
{
  "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.

```javascript
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:

```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](/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](/docs/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](/docs/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](/webhooks/guides/why-implement-asynchronous-processing-webhooks) and our [guide to webhook idempotency](/webhooks/guides/implement-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](https://hookdeck.com) 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](https://dashboard.hookdeck.com/signup) for free and handle Threads webhooks reliably in minutes.