RedditapisRedditapis
Live Monitoring

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

HeaderMeaning
x-redditapis-signaturet=<unix_seconds>,v1=<hex hmac>
x-redditapis-timestampThe same unix timestamp, for convenience
x-redditapis-delivery-idStable 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": [ ... ]
}
FieldMeaning
delivery_idSame value as the x-redditapis-delivery-id header. Deduplicate on it.
monitor_idThe monitor that matched.
countHow many items are in this delivery.
groupedWhether several matches were bundled into one delivery.
itemsThe 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.

Fieldnull when
textThe post may be a self post and its body could not be read.
is_selfNeither the post's link_url nor its body says which kind it is.
upvote_ratioReddit computes it and the page does not show it; it has no default.
link_urlA self post (always), or a link post whose target the page hid.
link_flair_text, link_flair_template_idThe post has no flair.
upvotes, commentsThe subreddit hides fresh scores, or the card did not carry them.
created, created_utcThe source carried no timestamp.
author_info, video, gallery_images, is_gallery, crosspost_originThe source did not carry them, or they do not apply.
enrichment fieldsThe 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.idid
comment.data.scoreupvotes
comment.data.link_id minus t3_post_id
comment.data.parent_idparent_id
comment.data.is_submitteris_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:

AttemptDelay before it
1immediate
25 seconds
330 seconds
42 minutes
55 minutes
613 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_modeWhat you get
instantOne email per match, sent within about a minute of the match.
hourlyOne email per clock hour (UTC) listing that hour's matches.
dailyOne email per day (UTC) listing that day's matches.
digestThe 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.

On this page