For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook

Send your Adalysis alerts to your own systems as signed JSON

The webhook integration sends every Adalysis notification as a JSON POST request to a URL you choose. Use it to feed alerts into your own systems, or into automation tools such as Make, n8n, Pipedream or Power Automate.

Each request is signed, so your endpoint can check that it really comes from Adalysis.

What you can send to a webhook

  • Performance monitor alerts (on Meta logins these include rule findings)

  • Performance goal alerts

  • Critical alerts (issues stopping your ads from running), for Google Ads and Microsoft Ads logins

  • Routine tasks reminder, for Google Ads and Microsoft Ads logins

  • Health alerts, for Meta logins

  • Budget spend alerts

  • Budget pacing alerts

  • Budget rollover

Webhooks also receive the notices Adalysis always sends, whatever is ticked: when it couldn't do something it was asked to do (for example, campaigns that couldn't be paused, budget changes that failed, or budget automation turned off because Google refused its changes), conversion set alerts, and connection alerts when a login loses access to its ad platform.


Before you connect

  • The Owner and Admins can add and remove webhooks and choose which webhook each login uses. An Admin can only choose webhooks for the logins they can open, and can't remove, test, rotate the key of or change a webhook that also serves logins they don't manage.

  • Your endpoint must:

    • use an https URL on port 443;

    • be reachable on the public internet (addresses on a private network are refused);

    • accept a JSON POST and reply with a 2xx status within 10 seconds.

  • Redirects are not followed, so use the final URL.

  • Each login sends to one webhook. An Adalysis account can have up to 20 notification destinations in all (Zapier hooks, Microsoft Teams workflows, webhooks and Google Chat spaces together; Slack channels don't count).


Setting it up

  1. Open your Adalysis account (the tile at the top of the rail on the left) and go to Notifications. On the Notification destinations card, click Add a Webhook endpoint.

    Open your Adalysis account (1), Notifications (2), then Add a Webhook endpoint (3)
  2. Give it a name (for example, the system it feeds), paste your Endpoint URL and click Add.

    Add a Webhook endpoint: a name (1), the endpoint URL (2), then Add (3)
  3. Adalysis sends a test event to your endpoint first. If your endpoint refuses it (a 4xx status), doesn't answer, or its address can't be found, the webhook isn't added. If it answers with a 5xx status, the webhook is added anyway, and you'll be asked to send it a test event later.

  4. Copy the signing key shown at the top of the Notification destinations card, under Signing key of your webhook's name. It is shown only once. If you lose it, click Rotate key next to the webhook to get a new one (the old key stops working straight away).

  5. Under Ad platform logins, the new webhook is already chosen in the Webhook column for every login that didn't have one. To change a login's webhook, or turn it off with No Webhook, choose it and click the Save next to it.

  6. Open each login in the app, go to Settings > Notifications and tick the Webhook column for each notification you want sent there, then click Save. On a team, only the login's main user can change this column; other team members see it read-only.

Scheduled notifications arrive at the delivery time and time zone set in the login's Settings > Notifications. Budget alerts are sent as soon as they happen.

Tip: each webhook on the Notification destinations card has a Send test event button, with a list of examples (for example, Example: Budget pacing alerts). Use it to see the exact data your endpoint will get for each kind of notification.


Verifying the signature

Every request has an X-Adalysis-Signature header:

  • t is the time the request was signed, in Unix seconds.

  • v1 is the hex-encoded HMAC-SHA256 of t, a full stop, and the raw request body (t + "." + body). The HMAC key is the whole signing key exactly as it was shown, encoded as UTF-8 text (do not base64-decode it).

To verify a request:

  1. Recompute the HMAC over the raw body, before any JSON parsing.

  2. Compare it with v1 using a constant-time comparison.

  3. Reject requests whose t is more than a few minutes old, to block replays.

Python:

Node.js:


The request body

Adalysis sends one request per notification and ad account. The exceptions are the routine tasks reminder, which is sent once per login, and connection alerts, which are sent once per login that lost its connection. The body is JSON (Content-Type: application/json). Every field is always present and set to null when it doesn't apply.

Field
Description

schema_version

Version of this format, currently 1

event_id

Unique ID of this event

event_type

The kind of notification (see below)

event_label

Its readable name

category

alert, system (something Adalysis couldn't do), connection or test

routable

true for notifications you can turn on and off in Settings > Notifications

test

true for test events sent from the Notification destinations card

sent_at

When it was sent (ISO 8601, UTC)

dedupe_key

Identical for repeats of one notification for one account on one day; use it to skip duplicates. Budget alerts add the budget group (g0 for the account's own budget) and connection alerts the login. null for test events

platform

google, microsoft or meta

login.email

The login the notification came from

account

The ad account: id, display_id (as shown in the ad platform), name and currency

title, text

A headline and a plain-text summary

url

A link to the right screen in Adalysis

details

Extra values specific to the event type

items

The rows of the notification (campaigns, budgets, alerts…); their fields depend on the event type. At most 200 rows

item_count

The total number of rows, including any cut off

items_truncated

true when there were more than 200 rows

Event types

event_type

Notification

perf_monitor_alert

Performance monitor alerts

perf_goal_alert

Performance goal alerts

critical_alerts

Critical alerts

routine_tasks_reminder

Routine tasks reminder

budget_spend_alert

Budget spend alerts

budget_pacing_alert

Budget pacing alerts

budget_rollover

Budget rollover

rule_findings

Rule findings (Meta rules; sent with Performance monitor alerts)

meta_health_alerts

Health alerts (Meta)

campaign_pausing_failed

Campaigns could not be paused

video_campaigns_to_pause

Video campaigns to pause by hand

auto_manage_disabled_total_budgets

Budget automation turned off for total budgets

auto_manage_disabled_refused_changes

Budget automation turned off: Google refuses its changes

budget_modification_failure

Budget changes failed

conversion_set_alert

Conversion set alerts

connection_alert

A login lost its connection to its ad platform

test

A test event

New event types and new fields may be added over time. Ignore any you don't recognise.


Changing or removing a webhook

To send a login to a different webhook, choose the new one for that login under Ad platform logins and click Save. To stop using a webhook, click Remove next to it.

If your endpoint replies 410, or keeps replying 401, 403 or 404 (three times in a row, over at least 45 minutes), or can't be reached at all for several days, it shows Webhook stopped accepting it: send a test event once it is fixed on the Notification destinations card and the account's owner gets an email about it. Fix the endpoint, then click Send test event to reconnect it. Temporary errors, such as a 5xx reply, don't disconnect it.

For everything else, such as delivery time, email address and which accounts you get notified about, see Notifications.

Last updated