Set up alert rules

An alert rule says which finding to watch for in a project and where to send it. Alerts are created from the monitored Google and Bing text-ad checks your project already runs, so they use no extra checks.

1. Open Alerts in the sidebar and select Rules. The Alert rules page opens.
2. Under Add rule, choose the project and the event type.
3. Optionally, limit the rule to one search engine, one device or a country code such as US.
4. Choose a channel: Email, Slack or Webhook, enter the destination and select Add rule. It appears under Configured rules.

Event types

• New advertiser observed: a domain your project does not own shows an ad on your monitored searches for the first time.
• Advertiser observed again: a domain shows an ad again after at least 30 days without being seen, while your checks kept running.
• Brand mention to review: an ad from a domain you do not own mentions your brand in its title or description. Domains you classified as authorized retailers are skipped.
• Affiliate ID observed: an ad's destination URL carries your project's affiliate parameter. Set the parameter in project settings first.

Scheduled summaries

Choose Scheduled summary as the type to get a short report on a schedule, even when nothing changed. Pick Every day or Every week, the day for a weekly summary (Monday by default) and the time (08:00 by default). The time uses your own time zone, and the rule keeps that zone when a teammate in another zone edits it later.

• Each summary covers the complete days before it is sent: the previous day, or the previous seven days for a weekly summary.
• It lists checks saved against the checks your schedule expected, new and returning advertisers, brand mentions, affiliate IDs, non-compliant affiliates, policy cases and the top advertisers by observed visibility, with links that open the same days and filters in the app.
• When no check was saved in the period, the summary says so instead of showing zeros. Failed check attempts are listed as unavailable results, not as zero ads.
• The engine, device and country restrictions work as in other rules.
• Select Preview next to the rule to see what the next summary would contain so far, and Send a test to receive the latest summary now, marked as a test.
• If the service was down at the scheduled time, you get the latest missed summary once, never a backlog.

Delivery channels

• Email: leave the destination empty to send to the account owner, or enter the address of a teammate in this account who has confirmed it. Other addresses are refused. The message explains the finding and links to the saved ads behind it.
• Slack: enter a Slack incoming webhook URL for the channel that should receive alerts.
• Webhook: enter an HTTPS URL on your own system. Ads Lighthouse sends a POST request with the event type and details as JSON, signed with a secret that belongs to the rule.
• When one check finds more than 10 new events for a rule, you get one digest that lists them instead of a message for each.
• Select Send a test next to a rule to check its destination. Test alerts are limited to 5 per rule per hour and 20 per account per day.

Verify webhook signatures

Each webhook rule has its own signing secret. Account owners and administrators find it on the Alert rules page under Webhook signing secrets: select Show signing secret, then Copy. Members do not see secrets.

1. Read the x-ads-lighthouse-signature header. It looks like t=1790000000,v1=5f2c…, where t is the Unix time in seconds when the request was signed.
2. Take the raw request body exactly as received, before parsing the JSON, and build the text t, a period and the body.
3. Compute the HMAC-SHA256 of that text with the rule's secret, as lowercase hex, and compare it with the v1 value using a constant-time comparison.
4. Refuse the request when the signatures differ or when t is more than 5 minutes away from your server's clock.
5. Keep the x-ads-lighthouse-delivery id of each processed request and ignore repeats. A retry keeps the id and is signed again with a new t.

The Webhooks integration page has ready-to-use examples for Node.js and Python.

Only send alerts to people and systems allowed to see that project's information. Alert content can include advertiser domains and ad text.