Alerts

Create an alert rule (email, Slack or webhook)

Creates an alert rule for a project, exactly like Settings > Alert rules. Types: competitor_new (a domain the project does not own shows an ad for the first time), competitor_returning (an advertiser returns after at least 30 days away), hijack_detected (an ad from another domain mentions the brand in its copy), affiliate_detected (one of your affiliate IDs appears in an ad's destination URL; needs the project's affiliate parameter), summary_digest (a scheduled summary sent daily or weekly at a local hour, even when nothing changed: checks saved against expected, new and returning advertisers, brand mentions, affiliate IDs, non-compliant affiliates, policy cases and the top advertisers by observed visibility for the complete local days before delivery; give cadence, weekday for weekly, hour and optionally time_zone). Channels: email (target is an address, or omit it to notify the account owner), slack (target must be an https://hooks.slack.com/services/ URL) or webhook (target must be a public HTTPS URL; each delivery is signed with HMAC-SHA256 in x-ads-lighthouse-signature). Optional engines, devices and countries restrict which observations fire the rule. Alerts are leads to review: an observation is not proof of a purchased keyword, spend or a violation. Requires the write scope and an idempotency key; a retry with the same key returns the same rule. For webhook rules the response carries the signing secret once.

post/alert-rules

Request

  • Base URL: https://adslighthouse.com/api/v1
  • URL: https://adslighthouse.com/api/v1/alert-rules
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

A unique value you choose for this request, such as a UUID. Repeating the same key returns the first result instead of starting paid work again.

Request body

project_idstring required

The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.

type'competitor_new' | 'competitor_returning' | 'hijack_detected' | 'affiliate_detected' | 'summary_digest' required

What fires the rule: a finding, or a schedule for summary_digest.

channel'email' | 'webhook' | 'slack' required

How alerts are delivered.

targetstring

For email, the confirmed address of a person in this account (empty sends to the account owner); otherwise a Slack incoming webhook URL or your HTTPS webhook URL.

enginesstring[] nullable

Only observations from these search engines. Omit or null for every engine.

devicesstring[] nullable

Only observations on these devices. Omit or null for every device.

countriesstring[] nullable

Only observations in these ISO 3166-1 alpha-2 countries, such as US.

cadence'daily' | 'weekly'

summary_digest only: daily or weekly. Required when creating a summary.

weekday'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday'

summary_digest only: the day of a weekly summary. Default monday.

hourinteger

summary_digest only: local delivery hour, 0 to 23. Default 8 (08:00).

time_zonestring

summary_digest only: IANA time zone such as America/New_York. Defaults to the acting person's time zone when creating, and keeps the stored zone when updating.

Response

Create an alert rule (email, Slack or webhook)

createdboolean required

False when this key already created the rule.

signing_secretstring nullable required

The webhook signing secret (whsec_...). Returned only here and by rotate_webhook_secret, only for webhook rules and only to owners and account admins. Store it now: list and get never return it.

request_idstring

Changes

No recorded changes to this operation across all 1 revision of this API.