Skip to main content

Webhooks

Webhooks allow you to integrate Redd directly into your own applications, bots, or automation workflows (like Zapier or Make). When a monitor finds a match, Redd sends a POST request to your configured URL.

Configuration

To enable webhooks for a monitor:

  1. Open the monitor settings.
  2. Enter your Webhook URL.
  3. Enter a Webhook Secret (any string of your choice). This is used to sign the payload.

Security: HMAC Signatures

Redd signs every webhook payload using your secret. This allows you to verify that the request actually came from Redd and hasn't been tampered with.

  • Header: X-Redd-Signature
  • Algorithm: HMAC-SHA256
  • Content: The signature is a hex-encoded hash of the raw request body using your secret as the key.

Verification Example (Node.js)

const crypto = require('crypto');

function verifySignature(payload, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return expected === signature;
}

Payload Structure

The webhook sends a JSON object containing the match details:

{
  "MonitorId": "uuid-string",
  "MonitorName": "My Monitor",
  "Match": {
    "Id": "reddit-id",
    "Type": "post",
    "Author": "username",
    "Subreddit": "python",
    "Title": "Check out this async library",
    "Body": "...",
    "Permalink": "https://reddit.com/r/...",
    "CreatedAt": "2023-10-27T10:00:00Z"
  },
  "MatchedValues": ["async"]
}

Retries and Failures

Redd expects a 2xx response from your endpoint. If your server is down or returns an error, Redd will attempt to redeliver the webhook a limited number of times before giving up.

Testing Webhooks

Use a service like Webhook.site to inspect the payload and signature before pointing Redd to your production server.