Ranknera for developers

#!/bin/sh
# List your sites with curl. RANKNERA_API_KEY is your key (rn_live_… or rn_test_…).
curl -sS "${RANKNERA_API_URL:-https://api.ranknera.com}/api/v1/sites" \
  -H "Authorization: Bearer $RANKNERA_API_KEY"

// Add a keyword to a site's queue, with Node's fetch. RANKNERA_API_KEY is your key; SITE_ID a site from GET /api/v1/sites.
// The Idempotency-Key makes a retry after a lost answer safe: the keyword is added once.
const base = process.env.RANKNERA_API_URL ?? "https://api.ranknera.com";

const res = await fetch(`${base}/api/v1/keywords`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RANKNERA_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ site_id: Number(process.env.SITE_ID), keyword: "best trail running shoes" }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
console.log(body.id, body.keyword, body.status);

"""List your articles waiting for review, with Python's standard library.
RANKNERA_API_KEY is your key (rn_live_… or rn_test_…)."""
import json
import os
import urllib.request

BASE = os.environ.get("RANKNERA_API_URL", "https://api.ranknera.com")
req = urllib.request.Request(f"{BASE}/api/v1/articles?status=manual_review&limit=20",
                             headers={"Authorization": f"Bearer {os.environ['RANKNERA_API_KEY']}"})
with urllib.request.urlopen(req) as res:
    page = json.load(res)
for article in page["data"]:
    print(article["id"], article["status"], article["keyword"])

{
  "id": "evt_3f1c…",
  "type": "article.published",
  "timestamp": "2026-10-24T09:30:00.000Z",
  "schema_version": 1,
  "mode": "live",
  "data": {
    "object": "article",
    "id": "184",
    "version": 1792833000123456,
    "detail": { "site_id": 3, "keyword": "best trail running shoes", "url": "https://example.com/best-trail-running-shoes" }
  }
}

// Verify a Ranknera webhook (Standard Webhooks) in Node, with no dependencies.
// secret: your webhook's signing secret (whsec_…); headers: the request's headers; body: the raw body text.
const crypto = require("node:crypto");

function verifyWebhook(secret, headers, body) {
  const id = headers["webhook-id"], timestamp = headers["webhook-timestamp"], signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // older than 5 minutes: refuse
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
  return signatures.split(" ").some((s) => {
    const [version, sig] = s.split(",");
    return version === "v1" && sig && sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  });
}

// For the docs' test: reads the body on stdin and the rest from the environment.
if (require.main === module) {
  let body = "";
  process.stdin.on("data", (c) => (body += c)).on("end", () => {
    const e = process.env;
    const ok = verifyWebhook(e.SECRET, { "webhook-id": e.WEBHOOK_ID, "webhook-timestamp": e.WEBHOOK_TIMESTAMP, "webhook-signature": e.WEBHOOK_SIGNATURE }, body);
    console.log(ok ? "valid" : "invalid");
  });
}

module.exports = { verifyWebhook };

"""Verify a Ranknera webhook (Standard Webhooks) in Python, standard library only.
secret: your webhook's signing secret (whsec_…); headers: the request's headers; body: the raw body bytes."""
import base64
import hashlib
import hmac
import os
import sys
import time


def verify_webhook(secret: str, headers: dict, body: bytes) -> bool:
    wid, ts, sigs = headers.get("webhook-id"), headers.get("webhook-timestamp"), headers.get("webhook-signature")
    if not (wid and ts and sigs):
        return False
    try:
        if abs(time.time() - int(ts)) > 300:  # older than 5 minutes: refuse
            return False
    except ValueError:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(hmac.new(key, f"{wid}.{ts}.".encode() + body, hashlib.sha256).digest()).decode()
    return any(v == "v1" and hmac.compare_digest(s, expected) for v, _, s in (p.partition(",") for p in sigs.split(" ")))


if __name__ == "__main__":  # for the docs' test: body on stdin, the rest from the environment
    e = os.environ
    ok = verify_webhook(e["SECRET"], {"webhook-id": e["WEBHOOK_ID"], "webhook-timestamp": e["WEBHOOK_TIMESTAMP"],
                                      "webhook-signature": e["WEBHOOK_SIGNATURE"]}, sys.stdin.buffer.read())
    print("valid" if ok else "invalid")

// Verify a Ranknera webhook (Standard Webhooks) in Go, standard library only.
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
	"io"
	"math"
	"os"
	"strconv"
	"strings"
	"time"
)

// VerifyWebhook: secret is your signing secret (whsec_…); id, timestamp and signatures are the
// webhook-id, webhook-timestamp and webhook-signature headers; body is the raw body.
func VerifyWebhook(secret, id, timestamp, signatures string, body []byte) bool {
	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if id == "" || signatures == "" || err != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
		return false
	}
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return false
	}
	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(id + "." + timestamp + "."))
	mac.Write(body)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
	for _, s := range strings.Split(signatures, " ") {
		parts := strings.SplitN(s, ",", 2)
		if len(parts) == 2 && parts[0] == "v1" && hmac.Equal([]byte(parts[1]), []byte(expected)) {
			return true
		}
	}
	return false
}

// For the docs' test: body on stdin, the rest from the environment.
func main() {
	body, _ := io.ReadAll(os.Stdin)
	if VerifyWebhook(os.Getenv("SECRET"), os.Getenv("WEBHOOK_ID"), os.Getenv("WEBHOOK_TIMESTAMP"), os.Getenv("WEBHOOK_SIGNATURE"), body) {
		fmt.Println("valid")
	} else {
		fmt.Println("invalid")
	}
}

<?php
// Verify a Ranknera webhook (Standard Webhooks) in PHP, no dependencies.
// $secret: your signing secret (whsec_…); $headers: the request's headers (lower-case names); $body: the raw body.
function verify_webhook(string $secret, array $headers, string $body): bool {
    $id = $headers['webhook-id'] ?? ''; $ts = $headers['webhook-timestamp'] ?? ''; $sigs = $headers['webhook-signature'] ?? '';
    if ($id === '' || $sigs === '' || !ctype_digit($ts) || abs(time() - (int)$ts) > 300) return false;
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret), true);
    if ($key === false) return false;
    $expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $key, true));
    foreach (explode(' ', $sigs) as $s) {
        [$v, $sig] = array_pad(explode(',', $s, 2), 2, '');
        if ($v === 'v1' && hash_equals($expected, $sig)) return true;
    }
    return false;
}

// For the docs' test: body on stdin, the rest from the environment.
if (PHP_SAPI === 'cli' && realpath($argv[0]) === __FILE__) {
    $ok = verify_webhook(getenv('SECRET'), ['webhook-id' => getenv('WEBHOOK_ID'), 'webhook-timestamp' => getenv('WEBHOOK_TIMESTAMP'),
        'webhook-signature' => getenv('WEBHOOK_SIGNATURE')], stream_get_contents(STDIN));
    echo $ok ? "valid\n" : "invalid\n";
}

# Verify a Ranknera webhook (Standard Webhooks) in Ruby, standard library only.
# secret: your signing secret (whsec_…); headers: the request's headers (lower-case names); body: the raw body.
require "base64"
require "openssl"

def verify_webhook(secret, headers, body)
  id, ts, sigs = headers["webhook-id"], headers["webhook-timestamp"], headers["webhook-signature"]
  return false if id.to_s.empty? || sigs.to_s.empty? || ts.to_s !~ /\A\d+\z/ || (Time.now.to_i - ts.to_i).abs > 300
  key = Base64.strict_decode64(secret.delete_prefix("whsec_"))
  expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{ts}.#{body}"))
  sigs.split(" ").any? do |s|
    v, sig = s.split(",", 2)
    v == "v1" && sig && sig.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(sig, expected)
  end
rescue ArgumentError
  false
end

# For the docs' test: body on stdin, the rest from the environment.
if __FILE__ == $PROGRAM_NAME
  ok = verify_webhook(ENV["SECRET"], { "webhook-id" => ENV["WEBHOOK_ID"], "webhook-timestamp" => ENV["WEBHOOK_TIMESTAMP"],
                                        "webhook-signature" => ENV["WEBHOOK_SIGNATURE"] }, $stdin.read)
  puts ok ? "valid" : "invalid"
end