Choosing a Delivery Method

Classification runs asynchronously: you submit a video, Gaard processes it, and the result becomes available a little later. This page explains the three ways to get that result out of Gaard so you can pick the one that fits your architecture.

There are two models:

• You pull the result when you are ready: polling.
• Gaard pushes the result to you as soon as it is ready: webhooks or SFTP delivery.

Each result (risk level, labels, scores, and the annotated highlight) is tied to a classify_id. Whichever method you choose, you are receiving the same underlying result.

Polling

Polling is the simplest option: after submitting a video, you call GET /api/result/<classify_id> until the status is done.

• You own the timing. Nothing has to be reachable from the internet: your system only makes outbound HTTPS requests.
• Same payload everywhere. The JSON returned by GET /api/result/<classify_id> is the same shape as a synchronous classify (POST /api/classify?sync=true) and the same shape webhooks send, so one parser covers every method.
• The trade-off is latency and traffic. You learn the result is ready only on your next poll, and a short poll interval means many requests that return “not done yet.”

Polling is a good first integration and the right choice when inbound callbacks are not possible in your environment. See Endpoints for the request and response details.

Webhooks

A webhook flips the direction: when a classification completes, Gaard sends an HTTP POST to an endpoint you run, carrying the result JSON.

• Lowest latency. Delivery is tied to completion: there is no poll interval to wait through.
• You run a receiver. You need an HTTPS endpoint that Gaard can reach.
• Delivery is best-effort. Gaard sends one POST per configured endpoint, does not retry, does not treat a non-2xx response as a retryable failure, and does not add a signature or authentication header. Protect your endpoint at the edge and make your handler idempotent.

Webhooks are configured per flow. For setup, the payload, and receiver recommendations, see Webhooks.

SFTP delivery

SFTP delivery writes the result to a server you control as files, rather than as an HTTP call. As each classification on the flow completes, Gaard connects to your SFTP/FTP server and drops either the annotated video or the snapshot images.

• File-based, not endpoint-based. You run an SFTP/FTP server instead of an HTTP receiver: a natural fit for video-management systems and batch or offline consumers.
• Files, not JSON. What lands on the server is media (an .mp4 clip or JPEG snapshots), not the result JSON. Reach for polling or webhooks if you need the structured result.
• Delivery is best-effort. A failed transfer is logged, not retried.

For configuration and the exact files that are written, see SFTP Delivery.

Tip

If your goal is to raise an alarm in a monitoring platform your operators already use (rather than to move raw results) see Alarm Platforms for Azursoft, Evalink, Prysm, and SIA DC-09.

Comparison

	Polling	Webhooks	SFTP delivery
Direction	You pull	Gaard pushes	Gaard pushes
Transport	HTTPS GET	HTTPS POST	SFTP/FTP file write
Latency	Depends on your poll interval	Near real-time	Near real-time
You must run	Nothing inbound	An HTTPS endpoint	An SFTP/FTP server
You receive	Result JSON	Result JSON	Video or snapshot files
Delivery guarantee	On demand, as reliable as your polling	Best-effort, one attempt, no retries	Best-effort file write
Scope	Per request	Per flow	Per flow
Best for	A first integration, or restricted networks	Event-driven pipelines	File-based, VMS, and batch consumers

Choosing

• Start with polling if you are integrating for the first time, cannot accept inbound connections, or want explicit control over when you fetch results.
• Move to webhooks once you operate an HTTP service and want near-real-time, event-driven processing without repeated polling.
• Use SFTP delivery when your consumer is file-based: a video-management system, an evidence archive, or a batch job that ingests clips and images rather than JSON.
• Combine them. You can poll and configure webhooks at the same time, and webhook delivery does not disable GET /api/result/<classify_id>. Configuring multiple destinations is how you fan a result out to several systems.

Next steps

• Webhooks: set up push delivery and design a reliable receiver.
• SFTP Delivery: deliver results as files to your own server.
• Alarm Platforms: connect Azursoft, Evalink, Prysm, and SIA DC-09.