Skip to main content

​
Custom headers

Each Custom Webhook integration can carry custom request headers — key/value pairs sent with every request. Use them for a bearer token, a static API key, or a routing header your gateway expects:
Practical guidance:
  • Keep the set small — roughly up to 20 pairs is plenty for any real use (auth + a couple of routing headers). theStacc does not enforce a count, but a sprawling header set usually signals something that belongs in the URL or body instead.
  • Content-Type cannot be overridden. theStacc always sends application/json. A custom Content-Type is ignored so your receiver’s JSON parser never breaks.
  • The signature headers cannot be overridden. Custom headers named X-Webhook-Signature or X-Fairview-Signature are ignored — theStacc always sets the real HMAC. This prevents a misconfigured (or malicious) custom header from spoofing the signature.
Everything else you set is passed through verbatim.

​
Limits and operational rules

​
Troubleshooting

Concrete error, then cause, then fix. For the user-facing side of these — where the error shows up in theStacc and how to recover — see Publishing Errors & Retries.

​
Security best practices

  1. Always set a webhook secret. Without one, anyone who guesses your URL can post fake blogs.
  2. Use crypto.timingSafeEqual / hmac.compare_digest when comparing signatures — plain === is timing-attack vulnerable.
  3. Hash the raw body, not the parsed JSON. Re-serialization changes whitespace and breaks signatures.
  4. Store the secret in env vars only. Never commit it to git, never include it in client-side code.
  5. Rotate the secret on suspected leak. Generate a new one, update both your env var and theStacc’s integration settings, then redeploy. theStacc starts signing with the new secret on the next request.
  6. Run your receiver behind HTTPS-only. Add HSTS if you control the domain.
  7. Rate-limit the receiver. Even with HMAC, a flood of unauthenticated requests can pressure your endpoint while you reject them. Cloudflare or your hosting platform usually handles this.

​
FAQ

How does the handshake work? There’s no traditional handshake — it’s stateless per-request authentication. The “handshake” is just storing a shared secret on both sides, once, during setup. Every subsequent request is independently authenticated via HMAC. What identifies a request as coming from theStacc? The X-Webhook-Signature header verified against your secret. Nothing else is reliable — anyone can fake the body, the User-Agent, or the source IP. What’s the X-Fairview-Signature header for? It’s a legacy compatibility header sent on autopilot publishes, carrying the same HMAC as X-Webhook-Signature but sha256=-prefixed. New receivers should use X-Webhook-Signature. See Legacy X-Fairview-Signature compatibility header. Why did the same blog arrive twice? Autopilot publishes retry automatically on transient failures, so a lost response packet can cause a re-delivery. Dedup on idempotency_key (autopilot payloads include it) or UPSERT on blog_id. See Idempotency & retries. Can I override the Content-Type or signature headers with a custom header? No. Content-Type is always application/json, and the signature headers are always set by theStacc. Custom headers with those names are ignored. What’s the maximum title / slug / content length? theStacc doesn’t enforce hard length limits at the API level — generated content stays well within reasonable bounds. If your CMS or DB needs hard caps, the Field reference table lists safe defaults. What if my receiver is slow or down when a publish happens? On a manual publish, that publish fails and the user clicks Republish. On an autopilot publish, theStacc retries automatically (up to 5 attempts over ~30 minutes) before marking it failed. See Publishing Errors & Retries. Can I get historical blogs through the webhook? No — webhooks are forward-only. For backfills, use the Public Blog API, which lets you fetch all your published blogs. Do I need to handle test.ping separately? Yes — it has no blog fields. If your handler tries to read title or content from a test.ping event, it’ll error and Test Connection will fail. Branch on event first. Can theStacc post to multiple webhook URLs? Yes — set up multiple Custom Webhook integrations on the same project. Each gets its own URL, secret, and headers, and theStacc fires every published blog at every active integration. Does an agent or the MCP server publishing my blog use a different webhook? No. Whether a teammate clicks Publish or an automation publishes through the MCP server, the publish flows through the same path and fires the same webhook events at the same URL. See Agent Keys & MCP. What happens if I delete a blog in theStacc? We send event: "blog.deleted" with the blog_id and title. Your handler should remove or hide the post. If your receiver fails, the blog stays deleted in theStacc but lingers on your site — periodic reconciliation via the Public Blog API is a defensive option.

​
Next steps