---
title: "Register Webhook"
method: POST
path: "/api/reddit/monitor/webhook/create"
tags: ["Monitoring"]
---

# Register Webhook

`POST /api/reddit/monitor/webhook/create`

## Request

- Base URL: `https://api.redditapis.com`
- URL: `https://api.redditapis.com/api/reddit/monitor/webhook/create`
- Auth: HTTP bearer

Register a delivery target for monitors to send matches to. Requires a recognised monitoring entitlement, which every account has: a free account can register a webhook for its free all-of-Reddit watch. Returns the webhook with its signing secret SHOWN ONCE, so store it immediately, it is never returned again by List Webhooks. Cost: Free per call.

## Request body

- object
  - `url` string, required: HTTPS URL to deliver matches to. Must be publicly reachable, no embedded credentials, no loopback/private/link-local address.
  - `kind` 'webhook' | 'slack' | 'discord' | 'email': Payload shape to send. Prefer omitting it: for a hooks.slack.com or discord.com/api/webhooks URL the kind is inferred from the host and the response reports it in kind_inferred_from. slack/discord format as native incoming-webhook messages; webhook sends redditapis' generic signed JSON envelope and is the fallback for an unrecognised host. Sending webhook for a Slack or Discord URL does not force the generic envelope (that combination can never deliver); the host wins and kind_corrected_from says so. Sending one specific kind for a different platform's host is refused with webhook_kind_mismatch (400).

## Response `200`

Successful response.

- object

## Other responses

- `400`: Bad request — missing or invalid parameters.
- `401`: Missing Bearer token.
- `402`: The account holds no recognised monitoring entitlement (subscription_required), a free account named a subreddit, which is a paid capability (subreddit_scope_requires_paid_plan), the plan's monitor slot limit is already in use (monitor_slots_exhausted), the plan's separate all-of-Reddit watch cap is reached (sitewide_slots_exhausted), or the account already watches as many distinct subreddits as the plan covers (distinct_subreddit_limit_reached). Note that every account holds a free entitlement of one all-of-Reddit post watch, so an account with no subscription is not by itself a 402.
- `403`: Invalid Bearer token.
- `429`: Rate limit exceeded.
- `500`: Unexpected server error.
- `502`: Upstream (Reddit) rejected the request — cookies expired or account flagged.

---

[API](https://skmtc.dev/redditapis/apis/redditapis-api.md) · [All operations](https://skmtc.dev/redditapis/apis/redditapis-api/llms.txt) · [OpenAPI document](https://skmtc.dev/redditapis/apis/redditapis-api/revisions/9696482dfe9b?raw)