Subscriptions

Manage webhook endpoints on https://hooks.theneuralledger.com. All routes need an API key.

API key required

Authorization: Bearer <your API key>

Subscriptions are scoped to your tenant. A key from another tenant cannot read, test, or delete yours — it gets a 404, not a 403, so the API never confirms that an id exists.

Create

POST /v1/webhooks/subscriptions

curl -sS -X POST https://hooks.theneuralledger.com/v1/webhooks/subscriptions \
  -H "Authorization: Bearer $TNL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/tnl",
    "eventTypes": ["intelligence.published", "intelligence.updated"],
    "filters": { "categories": ["Economic & Macro"], "geographies": ["Japan"] }
  }'

{
  "data": {
    "subscription": {
      "id": "sub_7hK2mQ",
      "url": "https://example.com/hooks/tnl",
      "eventTypes": ["intelligence.published", "intelligence.updated"],
      "state": "active",
      "activeKeyId": "key_UI2NWEcNW1ckYw"
    },
    "secret": "whsec_9f3c..."
  }
}

The secret is shown once

data.secret is returned only in this response. Store it immediately. If you lose it, rotate — you cannot read it back.

filters is optional. Omit it to receive every event of the requested types.

Endpoint requirements

The URL must be https, publicly resolvable, and must not point at a private or link-local address — the service refuses those to avoid being used to probe internal networks.

List

GET /v1/webhooks/subscriptions

curl -sS https://hooks.theneuralledger.com/v1/webhooks/subscriptions \
  -H "Authorization: Bearer $TNL_API_KEY"

Send a test event

POST /v1/webhooks/subscriptions/{id}/test

Delivers a subscription.test event immediately — the fastest way to prove signing and your receiver work end to end.

curl -sS -X POST \
  https://hooks.theneuralledger.com/v1/webhooks/subscriptions/sub_7hK2mQ/test \
  -H "Authorization: Bearer $TNL_API_KEY"

Returns 409 if the subscription is paused.

Pause and resume

POST /v1/webhooks/subscriptions/{id}/pause

Pausing stops delivery without discarding the subscription or its history — useful during a receiver deployment. Resume by completing the challenge on /verify.

Rotate the signing key

POST /v1/webhooks/subscriptions/{id}/rotate

Issues a new signing key and returns the new secret. The previous key id stays listed in previousKeyIds for an overlap window, so deliveries signed with either key verify while you roll out the new secret.

Verify against all keys you hold, selecting by TNL-Webhook-Key-Id, and drop the old one once no deliveries reference it.

Delete

DELETE /v1/webhooks/subscriptions/{id} → 204

curl -sS -X DELETE \
  https://hooks.theneuralledger.com/v1/webhooks/subscriptions/sub_7hK2mQ \
  -H "Authorization: Bearer $TNL_API_KEY" -o /dev/null -w '%{http_code}\n'

Deliveries and replay

GET /v1/webhooks/deliveries returns delivery history — status, attempt count, response code, and the failure reason for anything dead-lettered. The signing secret never appears in history.

Replaying a delivery re-sends the original payload with a newTNL-Webhook-Id, so a receiver deduplicating on that header will treat it as a new delivery. Deduplicate on the envelope id as well if a replay must be idempotent.

Replay requires operator permission; an ordinary key gets 403.

Health

Route	Meaning
GET /healthz	Service is up
GET /readyz	Database, queue, KMS, and identity are all reachable

curl -sS https://hooks.theneuralledger.com/readyz

{
  "ready": true,
  "service": "tnl-webhooks",
  "dependencies": {
    "database": "pass", "queue": "pass", "kms": "pass", "identity": "pass"
  }
}

Poll /readyz from your monitoring, not /healthz — a process can be running while its database is unreachable.