Webhooks

Receive real-time notifications when events occur in your Trakkr account. Integrate with Zapier, Make, Slack, Discord, and more.

Requires authentication

10 to 60 req/min

Overview

Webhooks allow you to receive real-time HTTP notifications when events occur in your Trakkr account. Instead of polling for changes, webhooks push data to your endpoint the moment something happens.

Supported Integrations

• Generic webhooks (any HTTPS endpoint)
• Zapier and Make (Integromat)
• Slack (with rich block formatting)
• Discord (with embed formatting)
• Microsoft Teams (with adaptive cards)

Event Types

Subscribe to one or more event types when creating a webhook. Every type listed here has a live producer behind it.

Event	Description
Visibility and competitive position
`visibility_changed`	Your visibility score moved beyond the alert threshold
`rank_changed`	A tracked competitor crossed your brand. Carries competitors_crossed
`competitor_changed`	A competitor's visibility moved beyond the alert threshold
`competitor_added`	A new competitor was detected or added
`report_completed`	A report finished. report_type is daily for the research run, or the document type when you call POST /get-reports
Citations
`citation_gained`	Brand gained a new citation source
`citation_lost`	A page that was being cited stopped appearing
`page_cited`	One of your pages was cited by an AI model
Perception
`perception_changed`	A perception score moved
`narrative_shift`	AI changed how it positions or talks about the brand
`descriptor_change`	The words AI uses to describe the brand turned over
`goal_achieved`	A perception goal reached its target
`goal_regression`	A perception goal slipped off track
Opportunities and content
`opportunity_found`	A citation opportunity was found
`prompt_gap`	AI answers a prompt with competitors and not you
`article_generated`	An article finished generating
`article_published`	An article was marked published
`campaign_completed`	Every article in a campaign finished
`research_completed`	A research run finished
Site health and crawlers
`audit_score_dropped`	Site AI readiness score dropped
`crawler_spike`	AI crawler traffic spiked above its normal daily average
`crawler_first_seen`	An AI bot crawled one of your pages for the first time
`crawler_silent`	A previously active AI bot stopped visiting
`crawler_error_surge`	AI crawlers started hitting broken pages
Actions
`action_created`	A new action landed in the queue
`action_completed`	An action was marked complete

If you are polling for fresh data, subscribe to report_completed instead. It fires when the daily research run lands and carries that day's visibility along with the change since the previous report, so you can act on the event without a follow-up read.

Cadence differs by family. Crawler events are near real time and crawler_first_seen is the highest volume of all, one per new bot and page pair. Visibility, ranking, citation and competitor events are detected when the daily research run completes. Content and action events fire as the work happens.

Create Webhook

POST/webhooks

Body Parameters

urlstringrequired

The webhook endpoint URL (must be HTTPS in production)

eventsarrayrequired

Array of event types to subscribe to

brand_idstringrequired

Brand UUID to receive events for

auth_typestring

Authentication: "none", "bearer", "basic", or "api_key"

Default: "none"

auth_tokenstring

Bearer token (if auth_type is "bearer")

signing_secretstring

Secret for HMAC-SHA256 signature verification

headersobject

Custom headers to include in webhook requests

The provider is automatically detected from the URL. Trakkr will format payloads appropriately for Slack blocks, Discord embeds, and Teams cards.

The Webhook Object

Webhook Schema

idstring

Unique webhook identifier

objectstring

Always "webhook"

urlstring

The webhook endpoint URL

eventsarray

Subscribed event types

brand_idstring

Brand UUID this webhook receives events for

providerstring

Detected provider: "webhook", "zapier", "make", "discord", "slack", "teams_webhook"

activeboolean

Whether the webhook is currently active

signing_secretstringnullable

Secret for verifying webhook signatures

created_atstring

ISO 8601 creation timestamp

Payload Format

Webhook payloads follow a consistent structure across all event types:

200 Delivered

1{
2  "event": {
3    "id": "evt_xyz789abc",
4    "type": "visibility_changed",
5    "triggered_at": "2026-01-09T14:30:00Z",
6    "data": {
7      "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
8      "previous_score": 42.5,
9      "current_score": 38.2,
10      "change_percent": -10.1,
11      "direction": "down"
12    }
13  },
14  "brand": {
15    "id": "00000000-0000-4000-8000-81f286d10c3c",
16    "name": "Notion",
17    "website": "https://notion.so"
18  },
19  "workflow": {
20    "id": "wf_123abc",
21    "name": "Visibility Drop Alert"
22  },
23  "summary": "Visibility dropped 10.1% from 42.5 to 38.2",
24  "meta": {
25    "source": "trakkr",
26    "version": "2.0",
27    "event_id": "evt_xyz789abc",
28    "timestamp": "2026-01-09T14:30:00Z"
29  }
30}

Payload Schema

eventobject

Event details including type, timestamp, and data

brandobject

Brand information (id, name, website)

workflowobjectnullable

Workflow that triggered this event

summarystring

Human-readable summary of the event

metaobject

Metadata including source, version, and idempotency key

Use the meta.event_id field for idempotency. Store processed event IDs to prevent duplicate handling if a webhook is retried.

Payload Templating

Customize webhook payloads using variable substitution with double curly braces:

{
  "text": "Alert: {{brand.name}} visibility changed!",
  "score": "{{event.data.current_score}}",
  "change": "{{event.data.change_percent}}%"
}

Available Variables

{{brand.id}}{{brand.name}}{{brand.website}}{{event.type}}{{event.data.*}}{{summary}}{{workflow.name}}{{timestamp}}

Authentication

Secure your webhook endpoints with one of the supported authentication methods:

Bearer Token

Set auth_type: "bearer" and provide auth_token. The token is sent in the Authorization: Bearer header.

Basic Auth

Set auth_type: "basic" with auth_username and auth_password.

API Key Header

Set auth_type: "api_key" with api_key_header and api_key_value.

Signature Verification

Verify webhook authenticity using HMAC-SHA256 signatures. When you provide asigning_secret, every request includes an X-Trakkr-Signature header.

X-Trakkr-Signature: sha256=abc123def456...

Verification Example (Python)

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Retry Logic

Webhooks are retried automatically on failure with exponential backoff:

3 retries with delays of 1s, 2s, 4s (exponential backoff)

5xx errors and timeouts trigger retries

429 rate limits respect the Retry-After header

4xx client errors (except 429) are not retried. Ensure your endpoint returns 2xx status codes to acknowledge receipt.

Provider-Specific Formatting

Trakkr automatically formats payloads for popular platforms:

Discord

Rich embeds with title, description, fields, and Trakkr green accent color.

Slack

Block Kit formatting with headers, sections, and context elements.

Zapier & Make

Standard JSON payload with all fields available for mapping.

Quick Reference

Endpoint	Description
POST`/webhooks`	Create a webhook
GET`/webhooks`	List webhooks
GET`/webhooks/:id`	Retrieve a webhook
DELETE`/webhooks/:id`	Delete a webhook
POST`/webhooks/:id/test`	Send a test webhook

Code example

1curl -X POST 'https://api.trakkr.ai/webhooks' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
6    "events": ["report_completed", "rank_changed"],
7    "brand_id": "00000000-0000-4000-8000-81f286d10c3c"
8  }'

200 OK

1{
2  "id": "whk_abc123xyz",
3  "object": "webhook",
4  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
5  "events": ["report_completed", "rank_changed"],
6  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
7  "provider": "zapier",
8  "active": true,
9  "signing_secret": "redacted-example",
10  "created_at": "2026-01-09T10:00:00Z"
11}

1curl -X POST 'https://api.trakkr.ai/webhooks' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
6    "events": ["report_completed", "rank_changed"],
7    "brand_id": "00000000-0000-4000-8000-81f286d10c3c"
8  }'

200 OK

1{
2  "id": "whk_abc123xyz",
3  "object": "webhook",
4  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
5  "events": ["report_completed", "rank_changed"],
6  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
7  "provider": "zapier",
8  "active": true,
9  "signing_secret": "redacted-example",
10  "created_at": "2026-01-09T10:00:00Z"
11}