Alert Pixel

The alert pixel is Pinokio’s push channel for Ad Verification. When you create a project, you can configure an alert_pixel URL. Pinokio fires a request at that URL when something happens that you should know about.

This is how you get notified without polling Scan Results on a timer.

When the pixel fires

Pinokio fires the alert pixel in two situations:

• Scan completed. Once a scan finishes for a project — whether it was on-demand (scan_now=1) or part of the recurring schedule (times_per_day) — Pinokio fires the pixel so your side knows results are ready to read.
• Change detected on a recurring project. When a project runs on a schedule and Pinokio notices that the ad creative or its placement changed between runs, the pixel fires to flag the change.

The pixel is a notification ping, not a verdict. To get the full detail of what changed or what was detected, follow up with Scan Results and Session Data.

How it works

1. You configure an alert_pixel URL when creating a project.
2. The project runs — on its schedule (times_per_day), on scan_now=1 at create time, or both.
3. When a scan completes or a change is detected, Pinokio hits the alert pixel URL.
4. Your endpoint reads the request, looks up the project, and triggers whatever you need on your side — page someone, update a status board, write a record into your warehouse, kick off a follow-up API call.

Endpoint requirements

There are no strict requirements on what your endpoint does — it just needs to be reachable from Pinokio’s scanning infrastructure. A few practical notes:

• Respond fast. Return 2xx as soon as you have the request. Do the actual processing asynchronously.
• Be idempotent. If you build retries into your alerting downstream, identical pings should not double up.
• Expect minimal payload. The alert pixel is a notification ping, not a results dump. Fetch the detail with Scan Results and Session Data.

Example flow

A typical chain when the pixel fires:

1. Pinokio hits your alert_pixel URL.
2. Your handler returns 200 immediately and queues a follow-up job.
3. The job calls /v1/project/scan_results/{project_id} with a tight date range around now and picks up the latest session ID.
4. The job calls /v1/project/session/{session_id} to fetch the full scan detail — what was scanned, what changed, what (if anything) was detected.
5. Your system records the result and notifies whoever needs to act.

Use the same URL across multiple projects if your downstream is generic. Use distinct per-project URLs (with project context baked into the path) if you want routing logic to happen at the load balancer instead of inside your handler.