Webhooks
Verify the HMAC-SHA256 signature, deduplicate on the delivery id, and understand the retry ladder before a delivery reaches you.
Every match is delivered as an HTTPS POST to the endpoint you registered.
Headers
| Header | Meaning |
|---|---|
x-redditapis-signature | t=<unix_seconds>,v1=<hex hmac> |
x-redditapis-timestamp | The same unix timestamp, for convenience |
x-redditapis-delivery-id | Stable id for this delivery. Deduplicate on this. |
The payload
The body is JSON. One delivery can carry more than one match, so items is
always an array even when it holds a single entry.
{
"delivery_id": "b6f0a1c2-...",
"monitor_id": "9d2e77f4-...",
"count": 2,
"grouped": false,
"items": [ ... ]
}| Field | Meaning |
|---|---|
delivery_id | Same value as the x-redditapis-delivery-id header. Deduplicate on it. |
monitor_id | The monitor that matched. |
count | How many items are in this delivery. |
grouped | Whether several matches were bundled into one delivery. |
items | The matches themselves. Shape depends on whether the monitor watches posts or comments. |
A test delivery (from Send Test or POST /api/reddit/monitor/webhook/test) has the shape of a real one: the same envelope keys, and one sample post in items with every field a real post match carries, including enrichment and matched_spans. It adds one key a real delivery never has, "type": "test", and nothing else. It is also told apart by its delivery_id, which always starts with test_, and by monitor_id being null. Skip anything with type: "test" in production logic. Send "item_kind": "comment" with the test request to receive one sample comment instead of a post, in exactly the shape a comment match has (below). Until October 21, 2026 a test also carried a short message key; it is gone, so the test envelope is the documented one.
Every match also carries enrichment (keyword relevance, sentiment and intent) and matched_spans, the places your terms were found (see Filters).
A match may also carry body_verified, a boolean. true means your terms were found in the item's own text. false means the post came from a sitewide keyword monitor (no subreddit), Reddit's own search returned it for that monitor's keywords, and its body could not be read to confirm the match, so it was delivered on Reddit's match: the title may not contain your terms, matched_spans may be empty and text may be missing. Such a match is only delivered to a monitor with no exclude_terms and without whole_words, and every other filter (kind, subreddits, author, NSFW, minimum score) still applies. Treat a missing body_verified as true.
A comment match
{
"id": "n1abc2d",
"author": "someuser",
"body": "the comment text",
"subreddit": "technicalanalysis",
"upvotes": 12,
"permalink": "/r/technicalanalysis/comments/1abcdef/some_thread/n1abc2d/",
"url": "https://reddit.com/r/technicalanalysis/comments/1abcdef/some_thread/n1abc2d/",
"post_id": "1abcdef",
"link_title": "the title of the parent post",
"link_url": "https://example.com/linked",
"parent_id": "t1_n1abc1c",
"is_submitter": false,
"created": "2026-08-25T09:00:00.000Z"
}post_id is the parent post's id with Reddit's t3_ prefix already stripped,
so you can pass it straight to GET /api/reddit/post/{postId}. upvotes is
Reddit's score. created is ISO 8601, not epoch seconds. parent_id is
Reddit's fullname of what the comment replies to, kept with its prefix: t1_
for a reply to another comment, t3_ for a top-level comment. is_submitter
is true when the commenter also wrote the post, and null when the source did not
say. upvotes is null while the subreddit hides fresh scores, never Reddit's
placeholder 1.
parent_id can be null. While Reddit refuses its .json reads, a
subreddit's new comments are read from its comment page, and that page does
not show what a comment replies to, so a comment delivered from it carries
parent_id: null. A comment delivered from that page also carries
upvotes: null where the subreddit hides scores.
Treat both as "not known", never as zero or as a top-level comment.
A post match carries the same fields as a post from
GET /api/reddit/posts?subreddit=, including link_flair_text and
link_flair_template_id (both null when the post has no flair).
Which post fields can be null
Since November 21, 2026 a post match read from Reddit's HTML pages no longer
carries null for a flag whose Reddit default is false: locked,
archived, over_18, spoiler, stickied and is_video are always true
or false. is_self is filled from the post itself when it can be (a
link_url off the post's own thread means a link post; a body with no
link_url means a self post), and a link post's text is "", as on Reddit.
Before sending, we also read up to 10 posts per delivery pass from Reddit to fill
text, is_self and upvote_ratio.
Every field below is still nullable. null always means "not known", never
false, zero or empty; a strict schema (Power Automate, Zapier, a typed
receiver) must allow null for each of them. The key is always present.
| Field | null when |
|---|---|
text | The post may be a self post and its body could not be read. |
is_self | Neither the post's link_url nor its body says which kind it is. |
upvote_ratio | Reddit computes it and the page does not show it; it has no default. |
link_url | A self post (always), or a link post whose target the page hid. |
link_flair_text, link_flair_template_id | The post has no flair. |
upvotes, comments | The subreddit hides fresh scores, or the card did not carry them. |
created, created_utc | The source carried no timestamp. |
author_info, video, gallery_images, is_gallery, crosspost_origin | The source did not carry them, or they do not apply. |
enrichment fields | The relevance scorer did not run on the item. |
This is the same shape deliveries returns
GET /api/reddit/monitor/deliveries?id=<monitor_id> answers with
{
"deliveries": [
{
"delivery_id": "b6f0a1c2-...",
"monitor_id": "9d2e77f4-...",
"webhook_id": "f7a817c8-...",
"status": "delivered",
"attempts": 1,
"retries": 0,
"last_error": null,
"created_at": "2026-08-25T09:00:01.000Z",
"delivered_at": "2026-08-25T09:00:01.480Z",
"payload": { "count": 2, "grouped": false, "items": [ ... ] }
}
]
}payload.items is byte-for-byte the same shape as the items you receive on
the webhook, so whatever parses your webhook body can be pointed at
deliveries[].payload.items unchanged. The extra fields on a delivery row are
transport state: status, attempts, last_error, created_at,
delivered_at, webhook_id.
It is NOT the same shape as GET /api/reddit/comment/{id}
That endpoint returns Reddit's raw object, passed through untouched:
{ "comment": { "kind": "t1", "data": { "id": "n1abc2d", "score": 12, "link_id": "t3_1abcdef", "created_utc": 1787654400 } } }Monitor items are flattened and normalised; /comment/{id} is not. If you need
to line the two up:
/comment/{id} | Monitor item |
|---|---|
comment.data.id | id |
comment.data.score | upvotes |
comment.data.link_id minus t3_ | post_id |
comment.data.parent_id | parent_id |
comment.data.is_submitter | is_submitter |
comment.data.created_utc (epoch seconds) | created (ISO 8601) |
Verifying the signature
The signed string is the timestamp, a literal dot, then the raw request body:
HMAC-SHA256(secret, `${timestamp}.${rawBody}`)Sign the bytes you received, not a re-serialised object. JSON.parse followed
by JSON.stringify can reorder keys or change number formatting, and the
signature will then fail for reasons that look like a wrong secret.
const crypto = require("node:crypto");
function verify(secret, header, rawBody, toleranceSeconds = 300) {
// header looks like: t=1786290000,v1=ab12...
const parts = Object.fromEntries(
header.split(",").map((kv) => kv.split("="))
);
const t = Number(parts.t);
if (!Number.isFinite(t)) return false;
// Reject stale timestamps, or a captured request can be replayed forever.
const age = Math.abs(Math.floor(Date.now() / 1000) - t);
if (age > toleranceSeconds) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
// Constant-time compare. A plain === leaks timing information about how much
// of the signature matched, which is enough to forge one byte at a time.
const a = Buffer.from(expected, "hex");
const b = Buffer.from(parts.v1 || "", "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}import hmac, hashlib, time
def verify(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
parts = dict(kv.split("=", 1) for kv in header.split(","))
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(int(time.time()) - t) > tolerance:
return False
expected = hmac.new(
secret.encode(),
f"{t}.".encode() + raw_body,
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))The tolerance window is 300 seconds. Anything older is a replay.
Retries
A delivery is retried when the attempt is worth repeating: a network failure, a 5xx, or a 429. Other 4xx responses are not retried, because a 400 or a 404 means the request will fail again and hammering someone's server with our name on it is abuse rather than persistence.
The ladder is front-loaded so a brief blip recovers quickly while a long outage backs off, and jittered so every customer's retries do not land on the same second after a shared incident:
| Attempt | Delay before it |
|---|---|
| 1 | immediate |
| 2 | 5 seconds |
| 3 | 30 seconds |
| 4 | 2 minutes |
| 5 | 5 minutes |
| 6 | 13 minutes |
Six attempts over roughly 21 minutes. After that the delivery is dead-lettered and visible on the monitor's health endpoint.
Respond 2xx as soon as you have durably accepted the payload, and do the work afterwards. Holding the connection open while you process makes slow work look like a failure and earns you a retry you did not need.
Secrets
The secret is shown once, when you create the webhook. We store it for
signing and cannot show it again. Rotate it with
POST /reddit/monitor/webhook/create and delete the old target, which lets you
run both briefly during a cutover.
URL rules
Registered URLs must be HTTPS and must resolve to a public address. Private ranges, loopback, link-local and cloud metadata addresses are rejected.
This is checked at delivery time, not only at registration, because a hostname that resolves publicly when you register it can resolve privately later. A URL that passes once is not trusted forever.
Slack and Discord
Register a webhook with kind set to slack or discord and paste the
incoming-webhook URL from that platform. The payload is shaped for that
service instead of our JSON envelope, so no receiving code is needed. Signature
headers do not apply, since the platform authenticates the URL itself. The URL
is a secret, so list, create and update responses mask it and set
url_masked: true.
When the matched post is an image submission, the image is rendered too: Slack
gets an image block under the title, Discord gets it as the embed image. This
covers a direct image link on Reddit's own media hosts, which is what an image
post is. A gallery, a v.redd.it video or a link post carries no single image
we can vouch for, so those render as before, with the title and the link. The
image is never re-hosted by us: both platforms fetch it from Reddit.
Email delivery
An email target sends matches to your account email address. Every plan can
have one, Free included. Choose how it arrives with delivery_mode when you
create it, and change it at any time with POST /reddit/monitor/webhook/update.
delivery_mode | What you get |
|---|---|
instant | One email per match, sent within about a minute of the match. |
hourly | One email per clock hour (UTC) listing that hour's matches. |
daily | One email per day (UTC) listing that day's matches. |
digest | The default. One email every 15 minutes listing the matches since the last one. |
An instant email carries the same item fields a webhook delivery does: the post title (or comment text), the subreddit, the author, a text snippet, when it was posted, its score and comment count when known, and the link to the thread on Reddit.
Instant emails are capped at 60 per address per hour. Past that, the rest of that hour's matches are collected into one email sent when the hour turns, and that email says so. Instant emails then resume on their own. Nothing is dropped; the cap only changes how the matches are grouped.
A digest lists up to 15 matches and states how many more there were. Every
match is also in GET /reddit/monitor/deliveries and your dashboard.
Unsubscribe
Every alert email has an Unsubscribe link and the standard one-click
unsubscribe headers, so your mail app's own unsubscribe button works too. It
pauses that email target without a login; your monitors keep running and keep
delivering to any other targets. To turn the emails back on, send
{ "id": "<webhook_id>", "active": true } to POST /reddit/monitor/webhook/update,
or press Resume on the address in your dashboard. Creating a new monitor
never quietly re-enables a target you paused.
Independent third-party API for developers and researchers. Not affiliated with, endorsed by, or sponsored by Reddit, Inc.
