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.comThis is a separate host from the read API (theneuralledger.com). It uses the same API keys.
When to use webhooks
| Use webhooks | Use 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
| Type | Fires when |
|---|---|
intelligence.published | A new story is published |
intelligence.updated | A published story is revised |
intelligence.retracted | A story is withdrawn |
intelligence.impact_changed | A story's market-impact paths change |
digest.weekly_published | The weekly digest is released |
subscription.test | You 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.
{
"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.