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.
Webhooks come with Pro and Ultra. Only the project owner can add one.
Set up a webhook
- Open the Integrations page of your project and find Webhooks. Only the project owner can add one.
- Enter the address that should receive events and choose the events you want.
- Copy the signing secret, which starts with
whsec_. You will only see it once. - 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
| Event | Sent when |
|---|---|
match.created | A new match at or above your score threshold is found. One event per match |
match.stage_changed | A match moves to another stage, from the app, the API or the MCP server. The event adds from and to |
ping | You 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:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | HearBuyers-Webhooks/1 |
X-HearBuyers-Event | The event name, such as match.created |
X-HearBuyers-Delivery | An id for this event and webhook. It stays the same on every retry, and is test for a ping |
X-HearBuyers-Signature | t=<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:
| Field | Meaning |
|---|---|
id | The match id. Use it with GET /v1/matches/{id} |
url | Link to the match in the app |
score, intent | Buying intent from 0 to 100, and actively_looking, comparing, complaining or just_curious |
keySentence, reason | The sentence that matched, copied from the post, and why it matched |
stage, foundAt | The stage now and when HearBuyers found the match |
listeners | The names of the listeners that found it |
post | source, community, url, title, body (the first 1,000 characters) and postedAt |
author | handle, 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:
- 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.
- Split the
X-HearBuyers-Signatureheader intotandv1. - Compute the HMAC-SHA256 of
t, a dot and the raw body, with the secret. - Compare it with
v1in constant time. - Reject the delivery if
tis 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-Deliveryto skip ones you have already handled. - Order is not guaranteed. A retried
match.createdcan arrive after a latermatch.stage_changedfor the same match. ComparefoundAtand thestagein 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.