Publish to Your Own Site (Custom Webhook)

What it is

If your site or app is custom-built (for example with Claude Code, Lovable, Cursor, or any Supabase or Firebase backend), you can publish ReachSurge articles straight to it. Add a "Custom site" target and, whenever you publish an article, we send a signed HTTP POST to a URL you control. Your endpoint verifies the request, stores the article, and rebuilds or renders it however you like.

This is available on Starter and above, the same as every other publish target.

Not the same as event webhooks

There are two different webhook features, and it is easy to confuse them:

• Custom site (this article): we PUSH your published article content to your endpoint so your site can display it. Set up under Settings, then Integrations, then Custom site.
• Event webhooks: we notify you when something happens (a new citation, a verified backlink, a completed crawl). Those are covered in Webhooks and are set up under Settings, then Webhooks.

If you want articles on your site, use Custom site. If you want event notifications, use event webhooks.

Setup

1. Go to Settings, then Integrations, then Custom site.
2. Paste your public HTTPS endpoint URL (for example https://yourapp.com/api/reachsurge-webhook).
3. Save. You receive a signing secret (starting with whsec_) shown once. Copy it now and store it as a server environment variable. It is never shown again. To rotate it later, reconnect with rotation enabled.
4. Build your receiver to verify the signature (see below), then click Send test event to confirm it works before publishing a real article.

Your endpoint must be a public HTTPS URL. Private, localhost, and internal addresses are rejected.

What we send

On publish we POST JSON to your endpoint with these headers:

X-ReachSurge-Event: page.published
X-ReachSurge-Timestamp: <unix seconds>
X-ReachSurge-Signature: sha256=<HMAC-SHA256 of "timestamp.rawBody" with your secret>
X-ReachSurge-Delivery: <per-delivery id, dedupe on this>

The body carries the full article:

{
  "event": "page.published",
  "page": {
    "id": "...", "title": "...", "slug": "...",
    "content_markdown": "...", "content_html": "...",
    "meta_description": "..." , "keywords": ["..."],
    "canonical_url": "...", "cover_image_url": "..." ,
    "published_at": "..."
  },
  "website": { "id": "...", "domain": "..." }
}

Verifying the request

Recompute the HMAC-SHA256 of timestamp + "." + rawBody using your signing secret, then compare it (constant-time) to the X-ReachSurge-Signature value with the sha256= prefix removed. Reject the request if the X-ReachSurge-Timestamp is more than five minutes old (replay protection). Dedupe on X-ReachSurge-Delivery so a retry does not create a duplicate post. Copy-paste receiver snippets for Next.js, Supabase edge functions, Firebase, and Express live under Settings, then API Keys, then API Docs.

When an article is unpublished

If you unpublish or archive a live article, we send a page.unpublished event to the same endpoint, signed the same way. The payload carries no content, only the identifiers you already have:

{
  "event": "page.unpublished",
  "page": { "id": "...", "slug": "...", "canonical_url": "..." },
  "website": { "id": "...", "domain": "..." },
  "unpublished_at": "..."
}

Delete or hide your copy keyed on the same page.id you upserted on for page.published and content.updated. The delete is idempotent, so handling a redelivered event twice is harmless. This mirrors what pull-based Content API consumers get automatically: an unpublished article simply disappears from their next fetch.

FAQ

What if my endpoint is down when an article publishes? We wait up to five seconds for a 2xx response. A non-2xx reply or a timeout marks the delivery as failed, and you can retry it from the article's syndication history. Respond quickly and do your heavy work afterwards.

Is the content signed so I know it really came from ReachSurge? Yes. The HMAC signature is computed with your secret, which only you and ReachSurge hold, so a verified signature proves the request is genuine and untampered.

Can I also FETCH articles instead of receiving a push? Yes. See Content API if you would rather pull your published articles at build time than host a receiver.