Skip to content

Reddit webhook for new buyer matches

updated 13 November 2026

A HearBuyers webhook sends each new buyer to your URL as soon as we find them. When a post on Reddit or X scores at or above your threshold, HearBuyers makes an HTTPS POST with signed JSON containing the post, the person who wrote it, the sentence that matched and the reason it matched.

Use it to fill a CRM, post to a channel, or start a workflow in Zapier or Make without polling the API. It works as a webhook export: social listening matches land in your own systems as soon as they appear.

Add a webhook

Webhooks come with Pro and Ultra. Only the project owner can add one.

Set up a webhook

  1. Open the Integrations page of your project and find Webhooks. Only the project owner can add one.
  2. Enter the address that should receive events and choose the events you want.
  3. Copy the signing secret, which starts with whsec_. You will only see it once.
  4. Press Send a test. Your server should answer with a 2xx status.

The address must be HTTPS, no longer than 500 characters, with no username or password in it, and it must resolve to a public address. Local, private and link-local addresses are refused. HearBuyers checks the address it actually connects to, so a name that points inside your network won't work. Redirects are not followed. For development, put a tunnel in front of your local server.

A project can have 5 webhooks. To change a secret, delete the webhook and add it again. Webhooks stop when the project has no live plan and start again when it has one.

Events

EventSent when
match.createdA new match at or above your score threshold is found. One event per match
match.stage_changedA match moves to another stage, from the app, the API or the MCP server. The event adds from and to
pingYou press Send a test. It goes only to that webhook

Matches under your threshold don't send match.created. To read them, use the API with a lower minScore.

What a delivery looks like

Every delivery is a POST with a JSON body and these headers:

HeaderValue
Content-Typeapplication/json
User-AgentHearBuyers-Webhooks/1
X-HearBuyers-EventThe event name, such as match.created
X-HearBuyers-DeliveryAn id for this event and webhook. It stays the same on every retry, and is test for a ping
X-HearBuyers-Signaturet=<unix seconds>,v1=<hex signature>, explained below

The body has four fields: event, createdAt, workspaceId (your project's id) and data. Key order is not guaranteed. This match.created is a real delivery from a test project with a made-up post:

{
  "event": "match.created",
  "createdAt": "2026-11-13T15:30:10.431596Z",
  "workspaceId": "7282b8ea-abac-4bb1-adb4-d2778701c4e7",
  "data": {
    "id": "31361cf7-9aa2-4d78-aff3-3bdba82b856f",
    "url": "https://hearbuyers.com/app/inbox/31361cf7-9aa2-4d78-aff3-3bdba82b856f",
    "score": 81,
    "intent": "comparing",
    "keySentence": "Need something that routes email and chat into one queue.",
    "reason": "Is leaving a competitor over cost and describes the missing capability.",
    "stage": "open",
    "foundAt": "2026-11-13T05:46:01.967311Z",
    "listeners": [],
    "post": {
      "source": "x",
      "community": "",
      "url": "https://x.com/tidebook_maya/status/1857342198836412416",
      "title": "",
      "body": "Anyone switched off Helpwave recently? Our ticket volume doubled and the bill followed. Need something that routes email and chat into one queue.",
      "postedAt": "2026-11-13T05:46:01.962518Z"
    },
    "author": {
      "handle": "tidebook_maya",
      "name": "Maya Ortiz",
      "website": "https://tidebook.example"
    }
  }
}

data holds the same fields for both match events:

FieldMeaning
idThe match id. Use it with GET /v1/matches/{id}
urlLink to the match in the app
score, intentBuying intent from 0 to 100, and actively_looking, comparing, complaining or just_curious
keySentence, reasonThe sentence that matched, copied from the post, and why it matched
stage, foundAtThe stage now and when HearBuyers found the match
listenersThe names of the listeners that found it
postsource, community, url, title, body (the first 1,000 characters) and postedAt
authorhandle, name and website, empty when unknown

Drafts are not included. Fetch one with the API if you want it.

match.stage_changed adds from and to, and stage already holds the new stage:

{
  "event": "match.stage_changed",
  "createdAt": "2026-11-13T15:29:26.579404Z",
  "workspaceId": "7282b8ea-abac-4bb1-adb4-d2778701c4e7",
  "data": {
    "id": "84dab689-a674-4872-ad0f-821dcb1a4866",
    "url": "https://hearbuyers.com/app/inbox/84dab689-a674-4872-ad0f-821dcb1a4866",
    "score": 92,
    "intent": "actively_looking",
    "keySentence": "We would switch this month if it handles shared inboxes well.",
    "reason": "States a deadline, names the incumbent they are leaving and asks for a specific feature.",
    "stage": "replied",
    "from": "open",
    "to": "replied",
    "foundAt": "2026-11-13T11:46:01.967311Z",
    "listeners": [],
    "post": {
      "source": "reddit",
      "community": "sysadmin",
      "url": "https://www.reddit.com/r/sysadmin/comments/1p3k9aq/looking_for_a_help_desk_tool_that_does_not/",
      "title": "Looking for a help desk tool that does not charge per agent",
      "body": "Our support team is growing from 4 to 9 people and Helpwave wants a seat license for each one. Does anyone know a simple help desk with flat pricing? We would switch this month if it handles shared inboxes well.",
      "postedAt": "2026-11-13T11:46:01.962518Z"
    },
    "author": {
      "handle": "northwind_ops",
      "name": "",
      "website": ""
    }
  }
}

A ping is smaller:

{
  "event": "ping",
  "createdAt": "2026-11-13T15:29:26.553533Z",
  "workspaceId": "7282b8ea-abac-4bb1-adb4-d2778701c4e7",
  "data": {
    "message": "HearBuyers is connected."
  }
}

Check the signature

Anyone can POST to your URL, so check that a delivery came from HearBuyers before you trust it. The signature is a hex HMAC-SHA256 of the timestamp, a dot and the raw request body, keyed with your signing secret. Do these steps in order:

  1. Read the raw body as bytes or a string before you parse the JSON. Parsing and serialising again changes the bytes and breaks the signature.
  2. Split the X-HearBuyers-Signature header into t and v1.
  3. Compute the HMAC-SHA256 of t, a dot and the raw body, with the secret.
  4. Compare it with v1 in constant time.
  5. Reject the delivery if t is more than 5 minutes from now, so nobody can replay an old delivery.

In Node:

import crypto from "node:crypto";

export function isFromHearBuyers(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const a = Buffer.from(parts.v1);
  const b = Buffer.from(expected);
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

In Python:

import hashlib, hmac, time

def is_from_hearbuyers(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return fresh and hmac.compare_digest(parts["v1"], expected)

We ran both functions against deliveries from a test project. Each accepts a real signature and rejects a body changed by one character as well as a wrong secret.

Answer and retry

Answer with any 2xx status within 10 seconds, and do the slow work after you have answered. Any other result counts as a failure: a different status, a redirect, a timeout, or no connection.

HearBuyers makes up to 5 attempts. The first goes out within about 15 seconds of the event. The retries follow at 1 minute, 5 minutes, 30 minutes and 2 hours after the previous attempt. After the fifth failure it gives up on that event.

  • Deliveries can repeat. If your server answered but the answer got lost, the same event arrives again. Use X-HearBuyers-Delivery to skip ones you have already handled.
  • Order is not guaranteed. A retried match.created can arrive after a later match.stage_changed for the same match. Compare foundAt and the stage in the payload, or fetch the match from the API.
  • You can watch it. The Integrations page shows when the last delivery went out, the last error, how many deliveries are waiting and how many gave up this week.

Questions about the Reddit webhook

Does it send Reddit matches only?

No. A match is a post on Reddit or X, and post.source says which. If you only want one, filter on it in your handler.

Can I create webhooks with the API?

No. The project owner adds and removes webhooks in the app. The API reads matches and manages listeners.

Why did the events stop?

Check that the plan is live, that the webhook still exists, and what the last error on the Integrations page says. A webhook sends nothing while the project has no live plan.

Can I send events to localhost?

No. Only public HTTPS addresses work. Use a tunnel while you build, then switch to your real URL.

Does it work with Zapier or Make?

Yes. It sends ordinary signed JSON, so you can use the webhook address from a Zapier or Make trigger as the URL. Keep that address secret, because anyone who has it can post to it.

Get an API key

Keys are on your project's API page. The API, the MCP server and webhooks come with Pro and Ultra, so start the 7-day trial first. Pro allows 60 requests a minute per key, and Ultra allows 300.