Real-time webhooks

How it works

1. Email partners@realmgroup.global with your endpoint URL and filter.
2. We create a subscription, generate a unique signing secret, and share it back.
3. Every ~5 minutes we deliver new matching jobs via POST.
4. You verify the X-Realm-Signature header and ingest the payload.

Filter examples

JSON filters applied per subscription:

// Australian farm jobs only
{ "country": "au", "role_slug": "farm-jobs" }

// Any station jobs globally
{ "role_slug": "station-jobs" }

// New Zealand ranch and cowboy jobs
{ "country": "nz", "role_slug": ["ranch-jobs", "cowboy-jobs"] }

// All jobs, no filter
{}

Payload format

POST https://your-endpoint.example.com/webhooks/realm
Content-Type: application/json
X-Realm-Signature: sha256=<hex>
X-Realm-Event: job.published
User-Agent: REALM-Radar-Webhook/1.0

{
  "event": "job.published",
  "delivered_at": "2026-05-16T03:45:00.000Z",
  "item": {
    "id": "5990ac32-…",
    "title": "Station Hand — Outback Queensland",
    "summary": "…",
    "link": "https://realm-jobs-radar.vercel.app/jobs/listing/…",
    "source_name": "AgJobs Australia",
    "source_url": "https://...",
    "category": "station-jobs",
    "state_or_region": "QLD",
    "country": "au",
    "published_at": "2026-05-16T03:00:00Z"
  }
}

Verifying the signature

Compute sha256=HMAC-SHA256(secret, raw_body) as hex and compare to theX-Realm-Signature header using constant-time comparison.

// Node.js example
import { createHmac, timingSafeEqual } from 'crypto';

const expected = 'sha256=' + createHmac('sha256', SECRET)
  .update(rawBody)
  .digest('hex');

if (!timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-realm-signature']))) {
  return res.status(401).send('bad signature');
}

Reliability

• Deliveries are deduped per (subscription, job) — safe to retry.
• We retry up to 10 consecutive failures before pausing the subscription.
• 10-second timeout. Return any 2xx to acknowledge.
• If you miss deliveries, fall back to polling /feeds/all.json.