Skip to content

Recipes — webhook alerts

Filter-based webhook alerts let Tango re-evaluate a saved query on a schedule and POST you the matches as alerts.<query_type>.match events. These recipes are end-to-end how-tos for the most common monitoring use cases.

What's in this section

Recipe Goal
Vendor watchlist Get notified when specific UEIs win new contracts.
Awards by NAICS Stream new contracts in one or more NAICS codes (with optional agency / set-aside / dollar-floor refinements).
Track entity changes Monitor SAM.gov registration updates — status flips, address moves, NAICS reassignment, socioeconomic re-cert.
Grants by agency Track new grant opportunities at one or more agencies, optionally filtered by CFDA + applicant type.
Forecast pipeline Monitor upcoming opportunities in agency procurement forecasts (HHS, DHS, GSA, COMMERCE, DOE, TREASURY, DOI, DOL, DOT, VA, NRC).

Prerequisites

All recipes assume:

  • An active Tango account on any tier (filter alerts are available on Free)
  • An API key (X-API-KEY) — see Authentication
  • A configured webhook endpoint — Tango provisions the endpoint record for you; ask support if you don't have one yet
  • Your shared signing secret stored as TANGO_WEBHOOK_SECRET server-side

SDK quick reference

Each recipe shows three side-by-side variants. The snippets below are templates — substitute your own name, query_type, and filters. See webhooks-user-guide.md for the full canonical schema, including when the optional endpoint field is required.

# Template — replace the placeholders with your alert spec.
curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \
  -H "Content-Type: application/json" \
  "https://tango.makegov.com/api/webhooks/alerts/" \
  -d '{
    "name": "<your alert name>",
    "query_type": "<opportunity|contract|idv|ota|otidv|entity|grant|forecast>",
    "filters": { "<filter_name>": "<filter_value>" },
    "frequency": "realtime"
  }'

from tango import TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])
alert = client.create_webhook_alert(
    name="...",
    query_type="...",
    filters={"...": "..."},
    frequency="realtime",
)

import { TangoClient } from "@makegov/tango-node";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
const alert = await client.createWebhookAlert({
  name: "...",
  query_type: "...",
  filters: { "...": "..." },
  frequency: "realtime",
});

OR vs AND filter syntax

  • Within a single filter, OR is | — naics: "541511|541512" matches either.
  • Across multiple filters, the API takes the AND — agency: "DHS" + naics: "541512" matches only DHS opportunities in 541512.
  • One known exception: the uei filter on /api/contracts/ is single-value only. Multi-vendor watchlists need one alert per UEI — see the vendor-watchlist recipe.

Test the filter against the API first

Always verify your filter returns the data you expect against the underlying API before turning it into an alert. If /api/<resource>/?<filters> returns nothing, the alert will never fire.

# Same filters you'd pass to the alert
curl -H "X-API-KEY: $TANGO_API_KEY" \
  "https://tango.makegov.com/api/contracts/?funding_agency=DOD&naics=541512"
Report an issue with this page