Skip to content
TrakkrAPI

Webhooks

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

Requires authentication
30 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:

EventDescription
visibility_changedVisibility score increased or decreased significantly
report_completedA new research report has been generated
competitor_addedA new competitor was detected or added
citation_gainedBrand gained a new citation source
citation_lostBrand lost a citation source

Create Webhook

POST/webhooks

Register a new webhook endpoint to receive event notifications.

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": "75ffdeb9-0924-4ff9-8ded-c2470d73d224",
8      "previous_score": 42.5,
9      "current_score": 38.2,
10      "change_percent": -10.1,
11      "direction": "down"
12    }
13  },
14  "brand": {
15    "id": "75ffdeb9-0924-4ff9-8ded-c2470d73d224",
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

EndpointDescription
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

Create Webhook
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": ["visibility_changed", "report_completed"],
7    "brand_id": "75ffdeb9-0924-4ff9-8ded-c2470d73d224"
8  }'
200 OK
1{
2  "id": "whk_abc123xyz",
3  "object": "webhook",
4  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
5  "events": ["visibility_changed", "report_completed"],
6  "brand_id": "75ffdeb9-0924-4ff9-8ded-c2470d73d224",
7  "provider": "zapier",
8  "active": true,
9  "signing_secret": "whsec_abc123...",
10  "created_at": "2026-01-09T10:00:00Z"
11}
Press ? for keyboard shortcuts