Webhooks

Webhooks enable your systems to receive real-time notifications when events occur in AudienceGPT -- topic classifications, activation status changes, import completions, and more. Instead of polling the API for updates, you register an HTTPS endpoint and AudienceGPT pushes event payloads to it as they happen.

Coming Soon

Webhooks are on the AudienceGPT roadmap and will be available in a future release. This page documents the planned design so you can prepare your integration architecture. The event types, payload formats, and delivery semantics described below are subject to change before launch.

How Webhooks Work

AudienceGPT Event  -->  Serialize payload  -->  POST to your endpoint
                                                     |
                                            Your server returns 2xx
                                                     |
                                            Event marked as delivered

1. An event occurs in AudienceGPT (e.g., a topic is classified)
2. AudienceGPT serializes the event into a JSON payload
3. AudienceGPT sends an HTTP POST request to your registered endpoint
4. Your server processes the event and returns a 2xx status code
5. If delivery fails, AudienceGPT retries with exponential backoff

Planned Event Types

Event	Description
topic.classified	A new topic has been classified (via chat, API, or import)
topic.reclassified	An existing topic has been reclassified (new engine version or manual)
topic.deleted	A topic was removed from your library
import.completed	A CSV import batch finished processing
import.failed	A CSV import batch failed or was cancelled
activation.pushed	A segment was successfully pushed to a DSP platform
activation.deactivated	A segment was deactivated on a DSP platform
activation.stale	An activation was detected as stale (naming or version drift)
sync.completed	An inbound sync run finished
sync.failed	An inbound sync run failed
connection.test_failed	A platform connection test failed (health monitoring)

Planned Payload Format

All webhook payloads will follow a consistent envelope format:

{
  "id": "evt_01hy...",
  "type": "topic.classified",
  "created_at": "2026-02-25T10:00:00.000Z",
  "org_id": "org_01...",
  "data": {
    "topic_id": "ot_01hy...",
    "topic_name": "Tesla Model 3 Buyers",
    "parent_category": "Auto",
    "taxonomy_type": "Automotive & Vehicles",
    "segment_type": "B2C",
    "engine_version": "2.5",
    "source": "api"
  }
}

Field	Type	Description
id	string	Unique event ID for idempotent processing
type	string	Event type (see table above)
created_at	string	ISO 8601 timestamp (UTC)
org_id	string	Organization that owns the resource
data	object	Event-specific payload (varies by type)

Planned Security

Signature Verification

Each webhook request will include a signature header for payload verification:

X-AudienceGPT-Signature: sha256=a1b2c3d4e5f6...

The signature will be an HMAC-SHA256 digest of the raw request body, computed with your webhook signing secret. Verify it before processing any webhook payload:

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  const expectedBuffer = Buffer.from(`sha256=${expected}`, "utf8");
  const receivedBuffer = Buffer.from(signature, "utf8");

  if (expectedBuffer.length !== receivedBuffer.length) return false;
  return timingSafeEqual(expectedBuffer, receivedBuffer);
}

warning

Always use constant-time comparison (like timingSafeEqual) when verifying signatures. Standard string equality (===) is vulnerable to timing attacks.

Replay Prevention

Each webhook will include a timestamp header:

X-AudienceGPT-Timestamp: 1740400000

Reject any webhook where the timestamp is more than 5 minutes old to prevent replay attacks.

Planned Delivery Guarantees

Property	Value
Delivery	At-least-once
Retry schedule	Exponential backoff: 30s, 2m, 15m, 1h, 4h, 24h
Max retries	6 attempts over 24 hours
Timeout	30 seconds per delivery attempt
Success codes	Any 2xx status code
Idempotency	Use the id field to deduplicate events on your end

If all retries are exhausted, the event will be marked as failed. A webhook event log will be available in the dashboard for debugging failed deliveries.

Planned Endpoint Configuration

Webhook endpoints will be managed through the dashboard and API:

Endpoint	Method	Description
/api/webhooks	POST	Register a new webhook endpoint
/api/webhooks	GET	List registered webhook endpoints
/api/webhooks/:id	PATCH	Update endpoint URL or event subscriptions
/api/webhooks/:id	DELETE	Remove a webhook endpoint
/api/webhooks/:id/test	POST	Send a test event to verify your endpoint

Planned Registration Request

{
  "url": "https://your-app.com/webhooks/audiencegpt",
  "events": ["topic.classified", "activation.pushed", "import.completed"],
  "description": "Production webhook for topic sync"
}

Preparing Your Integration

While webhooks are not yet available, you can prepare by:

1. Design your handler endpoint -- Build an HTTPS endpoint that accepts POST requests and returns 2xx
2. Plan for idempotency -- Store processed event IDs to handle duplicate deliveries
3. Use polling as a bridge -- Poll the relevant APIs periodically until webhooks launch:
   • GET /api/topics with sortBy=created_at for new topics
   • GET /api/activations?status=active for activation changes
   • GET /api/import/:batchId/status for import progress
4. Set up signature verification -- Prepare your verification logic using the pattern above

Next Steps

• Topics API -- Poll for topic changes
• Activations API -- Poll for activation status
• Import API -- Poll for import progress
• SDK Integration -- Client-side integration alternative