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
httpsURL on port 443;be reachable on the public internet (addresses on a private network are refused);
accept a JSON
POSTand reply with a2xxstatus 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
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) 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) Adalysis sends a test event to your endpoint first. If your endpoint refuses it (a
4xxstatus), doesn't answer, or its address can't be found, the webhook isn't added. If it answers with a5xxstatus, the webhook is added anyway, and you'll be asked to send it a test event later.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).
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.
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:
tis the time the request was signed, in Unix seconds.v1is the hex-encoded HMAC-SHA256 oft, 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:
Recompute the HMAC over the raw body, before any JSON parsing.
Compare it with
v1using a constant-time comparison.Reject requests whose
tis 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.
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