Webhook Setup

Get notified the moment something changes — no polling required. Catalogian sends a POST to your endpoint with the delta summary whenever a change is detected.

Creating a webhook

Via the dashboard

Dashboard → Source → Webhooks tab → Add endpoint URL + optional signing secret.

Via the API

curl -X POST https://api.catalogian.com/v1/sources/:id/webhooks \
  -H "Authorization: Bearer $CATALOGIAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/catalogian",
    "secret": "whsec_optional_signing_secret"
  }'

When do webhooks fire?

Webhooks fire whenever a delta event has at least one change — new, changed, or deleted rows. No-change events (where isNoChange: true) do not trigger webhooks.

Payload preview

{
  "event": "delta",
  "webhookId": "wh_...",
  "sourceId": "cmmfyryl30005ygld7m5596gm",
  "sourceName": "West Coast Earthquakes",
  "deltaEventId": "evt_01j...",
  "detectedAt": "2026-09-28T20:00:00.000Z",
  "summary": {
    "newCount": 5,
    "changedCount": 3,
    "deletedCount": 0,
    "unchangedCount": 194,
    "totalCount": 202
  },
  "newKeys": ["nc75443740", "nc75443741"],
  "changedKeys": ["nc75443737"],
  "deletedKeys": []
}

Keys are capped at 100 per category. See the full payload reference for every field.

Managing webhooks

List, enable/disable, and delete webhooks via the API:

# List webhooks for a source
GET /v1/sources/:id/webhooks

# Enable or disable
PATCH /v1/sources/:id/webhooks/:webhookId
{ "enabled": false }

# Delete
DELETE /v1/sources/:id/webhooks/:webhookId

Plan requirement: Webhooks are available once any record is on a paid tier (Watch or Max).

Full payload schema with all fields. Payload Reference →

Secure your endpoint with HMAC signatures. Verifying Signatures →

Understand retry behavior and failure handling. Retry Logic →