This page is for developers who want to wire PubSentry into their own stack — provision sites in code, pull verdict data into a warehouse, or fire a webhook when a block lands. We will be straight about what exists today versus what is coming, because pointing you at an endpoint that may change tomorrow is worse than telling you it is not ready.
The short version: integration today is the tag. One async script protects a site end to end, no SDK and no API calls on your side. A stable, documented public API and outbound webhooks are on the roadmap (coming) — designed, previewed in the dashboard, not yet shipped. Read on for exactly how each piece works.
What ships today: the tag
The entire install is one line in your page <head>:
<script async src="https://pubsentry.com/t.js" data-site="st_xxxx"></script>Replace st_xxxx with your real site ID from app.pubsentry.com. That is the integration. The tag runs a sub-5ms local gate, blocks invalid visitors before the ad fires (block-before-serve), and beacons a signal payload back to PubSentry, which enriches it server-side (IP/ASN/geo from the request, device from the user-agent), scores it with the shared engine, updates reputation, and persists the event. There is no client API to call, no key to rotate, and nothing for you to poll.
The tag is configured entirely through data- attributes on that script element — data-site is the only required one. It reads a cached copy of your per-site config (protection mode, safety mode) synchronously on boot so the very first gate decision is correct, then refreshes asynchronously. For the full attribute list and verification steps, see Installing the PubSentry Tag.
For most publishers, this is the whole story. You never write code against PubSentry; you drop the tag and manage everything from the dashboard.
The /v1/* endpoints are private (not a public API)
You will see /v1/* requests in your browser's network tab when you use the dashboard — /v1/overview, /v1/timeseries, /v1/event, /v1/rules, /v1/alerts, and so on. These are real and they work, but they are not a public integration surface. Two things make them unsuitable to build against today:
- They are session-scoped to your account. Under M2 auth (live in production), every
/v1request requires a logged-in cookie session and is scoped to the sites your account owns. There are no API keys yet — only browser sessions. The dashboard and its APIs are same-origin onapp.pubsentry.com, so there is no CORS surface to call them from elsewhere. - Their shapes are internal. These routes exist to render the dashboard. Their request and response shapes can change whenever the UI changes, with no deprecation contract. Building automation against them means your integration breaks on a frontend refactor.
The one public, server-to-server /v1 route is the billing webhook receiver — POST /v1/billing/webhook — and that exists for DodoPayments to call us, not for you to call. It is the single endpoint exempt from the auth gate, and it is protected by Standard-Webhooks signature verification (more on that pattern below). It is not a general-purpose API.
So: treat /v1/* as the dashboard's private backend. If you have a real programmatic need today, talk to us and we will scope it honestly rather than hand you endpoints that may move.
What's coming: a documented public API
A first-class, versioned public API is on the roadmap. The design intent is the obvious set of things a developer wants:
- Provisioning — create and list sites, fetch a site's ID and config, without clicking through the dashboard.
- Read access to verdicts — pull scored events, summaries, and time series into your own warehouse or BI tool, on a stable contract with documented fields.
- Config as code — manage protection mode, rules, IP allow/deny lists, and alerts programmatically, so your detection config can live in version control alongside the rest of your infrastructure.
Authentication will be scoped API keys rather than the cookie sessions the dashboard uses — keys you can mint, label, and revoke, each restricted to specific sites. This is previewed in the dashboard today under API & Webhooks, which is honest about its status: it shows you exactly what unlocks (scoped keys, signed webhooks) and is explicitly not a live control pretending to be connected. It is slated to arrive with the Enterprise plan.
When this API lands, it will be versioned (the /v1 prefix is deliberate) and documented here with a change policy. Until then, do not build against the private endpoints.
What's coming: outbound webhooks
Today PubSentry pushes events outward in two ways: alerts (email/Slack/webhook notifications you configure per rule — see Alerts) and the in-app Notifications feed. Alerts already include a webhook delivery channel with an SSRF guard, so you can get a POST when an invalid-traffic spike, a policy finding, or an attack cluster fires.
The roadmap item is broader: first-class, signed event webhooks so you can stream PubSentry's security events straight into your own tooling — incident pipelines, SIEMs, on-call systems — without scraping the dashboard. The planned event types include:
block.fired— an invalid visitor was suppressed before an ad served.rule.applied— a rule you wrote (or approved from a recommendation) matched and acted.account_safety.dropped— your composite Ban-Risk / account-safety score moved into a worse band, the kind of signal you want to page on.
These will be signed using the Standard-Webhooks specification — the same scheme we already use to verify DodoPayments' billing webhooks on the inbound side. Each delivery carries webhook-id, webhook-timestamp, and webhook-signature headers; you verify the HMAC over the raw body before trusting the payload, and reject anything that does not match. That gives you authenticity and replay protection out of the box, with libraries available in most languages. This is the pattern to expect for every PubSentry webhook, so an integration you build against the billing-webhook shape will feel familiar when general event webhooks arrive.
A note on data and privacy
Whatever you build against, the data contract is the same one the rest of the product honors. Raw IP and user-agent are hashed server-side with HMAC-SHA256 and then dropped — they are never stored raw and will never appear in an API response or webhook payload. Device fingerprints are non-PII hashes. IP intelligence (datacenter/ASN/geo) comes from an offline dataset, so enrichment carries no per-request third-party call. Any future API and webhook surface inherits these guarantees; we are not going to expose raw PII through an integration we would not expose through the dashboard.
Where this leaves you today
If you are a publisher, the tag is everything — install it, manage from the dashboard, done. If you are a developer who needs provisioning, verdict export, or event streaming right now, the honest status is: the public API and signed webhooks are designed and previewed but not yet shipped. Alerts already cover the common "POST me when something fires" case. For anything beyond that, tell us what you are building so we can scope it against the real roadmap rather than against endpoints that may change underneath you.