Webhooks

iSearchFrom can POST an event to an endpoint you control whenever a tracking campaign raises an alert. This is the one outbound webhook the platform sends today: campaign alerts. Use it to route alerts into Slack, an incident tool, an internal dashboard, or a data warehouse.

Scope

Webhooks are alert deliveries, not a general event-subscription system. They fire when a position-tracker, ad-tracker, or AI-visibility campaign raises a notify-worthy alert and that campaign has a webhook URL configured. There is no subscribe-to-any-event API.

When to use webhooks

• Alerts need to enter an internal tool, Slack channel, or incident workflow.
• You want to store alert events in a data warehouse.
• Another workflow should run when a campaign’s rankings, ads, or AI visibility change.

For a complete walkthrough including a relay to Slack, see the cookbook Send alerts to Slack.

Configure a webhook

1. Open the campaign’s alert settings (in the app, or via the campaign’s alertSettings through the API).
2. Enable alerts and set a public HTTPS endpoint as the webhook URL.
3. Save the campaign.
4. Trigger a low-risk alert to confirm delivery before relying on it.

The endpoint must accept POST and return a 2xx quickly. If you need slow processing, acknowledge fast and process asynchronously.

Payload shape

Every delivery is JSON with this exact shape:

{
  "event": "tool.alert.created",
  "timestamp": "2026-07-07T14:05:00.000Z",
  "data": {
    "alertId": "…",
    "targetType": "position_campaign",
    "campaignId": "…",
    "campaignName": "Brand keywords — US",
    "type": "…",
    "severity": "…",
    "metadata": { "…": "…" }
  }
}

Field	Notes
event	Always tool.alert.created today. Branch on it; new event types may be added.
timestamp	ISO-8601 time the alert was raised.
data.alertId	Unique alert id — use it for idempotency (see below).
data.targetType	Which kind of campaign (position, ad-tracker, or AI-visibility).
data.campaignId	The campaign that raised the alert.
data.campaignName	The campaign’s name, for display.
data.type	The alert rule that fired.
data.severity	The alert’s severity.
data.metadata	Alert-type-specific detail (varies by type).

Handle unknown fields safely — new fields may be added without changing existing ones.

Delivery behavior

• Retries: a failed delivery is retried up to 4 times with exponential backoff (roughly 5s, 25s, 2m, 10m). After that it’s given up.
• Idempotency: the same alert can arrive more than once (a retry after your endpoint was briefly slow). De-duplicate on data.alertId if duplicates would matter.
• Response: return 2xx only once you’ve accepted the event. Use 5xx or a timeout for temporary failures (which trigger a retry); a 4xx still counts as a failed attempt.
• Keep responses small — iSearchFrom does not surface your endpoint’s response anywhere.

Security recommendations

• Use HTTPS and a unique URL per integration so you can rotate or revoke one independently.
• The webhook URL is effectively a secret — treat a leaked one as compromised and rotate it.
• If your receiver needs to authenticate the caller, put a secret token in your own URL path/query or use a gateway rule. Never put API keys in the webhook URL.
• Don’t put secrets in campaign names or alert labels — they appear in the payload.

Related docs

• Send alerts to Slack (cookbook)
• Schedules and Alerts
• AI Visibility Alerts
• Errors, Pagination, and Rate Limits