Skip to content

Webhooks ​

Webhooks push intelligence to your systems as it is published, instead of you polling for it. The Neural Ledger signs every delivery, retries failures with backoff, and keeps a replayable history so a receiver outage does not lose events.

The webhook service runs at:

https://hooks.theneuralledger.com

This is a separate host from the read API (theneuralledger.com). It uses the same API keys.

When to use webhooks ​

Use webhooksUse the API
You need new stories within seconds✅polling wastes quota
You are filling a database or queue✅
You need history, search, or backfill✅
Your receiver cannot accept inbound HTTPS✅

If you cannot expose an endpoint, use n8n, Zapier, or another connector, which host the receiver for you.

Event types ​

TypeFires when
intelligence.publishedA new story is published
intelligence.updatedA published story is revised
intelligence.retractedA story is withdrawn
intelligence.impact_changedA story's market-impact paths change
digest.weekly_publishedThe weekly digest is released
subscription.testYou call the /test endpoint

A subscription declares which types it wants. subscription.test is always delivered, so you can prove the pipe works without waiting for news.

Event envelope ​

Every delivery has the same shape. Schema version is 1.0.

json
{
  "id": "evt_0J8pQb2mXk",
  "type": "intelligence.published",
  "schemaVersion": "1.0",
  "occurredAt": "2026-07-30T09:14:02.117Z",
  "publishedAt": "2026-07-30T09:14:00.000Z",
  "tenantId": "ten_4XcR1v",
  "resource": {
    "id": "story_c253fc638c7f",
    "revision": 1,
    "url": "https://theneuralledger.com/article/Korean-Won-Surges-6-24-in-July"
  },
  "data": {
    "summary": "The Bank of Korea raised its policy rate...",
    "categories": ["Economic & Macro"],
    "geographies": ["South Korea"],
    "entities": ["Bank of Korea"],
    "assets": ["KRW"],
    "impactPaths": ["policy rate -> currency"],
    "confidence": 0.82,
    "language": "en",
    "provenance": ["https://example.com/source-article"]
  },
  "metadata": { "producer": "tnl", "traceId": "trc_9Kd2" }
}

resource.revision increments on every update, so you can discard an out-of-order intelligence.updated by keeping the highest revision you have seen per resource.id.

confidence and language are optional; the other data fields are always present, though arrays may be empty.

Delivery semantics ​

At least once. A delivery can arrive more than once — after a retry that actually succeeded the first time, or after you replay it. Deduplicate on TNL-Webhook-Id, which is stable across retries of the same delivery.

Ordered per resource, not globally. Use resource.revision rather than arrival order.

Retries use exponential backoff. A delivery that keeps failing lands in the dead-letter queue after 8 attempts, where it stays available for replay.

Respond 2xx to acknowledge. Any other status, or a timeout, counts as a failure and schedules a retry. If you return 429 with a Retry-After header, that value is honoured.

Acknowledge fast — do the work afterwards. A receiver that processes inline and takes longer than the timeout will be retried while still working on the first copy.

Next steps ​

The Neural Ledger API