Webhooks

Subscribe to real-time events from the NANDA registry. Webhooks deliver HTTP POST callbacks when agents are registered, certified, reputation scores change, or compliance violations occur.

Inline delivery: Webhooks are delivered inline (no queue infrastructure). The /api/queue/webhook-deliver endpoint is available for external callers but delivery happens synchronously during event dispatch. A circuit breaker disables subscriptions after 10 consecutive failures.

Event Types

EventDescription
agent.registeredNew agent registered or updated
agent.deprecatedAgent deprecated or tombstoned
cert.issuedCertification issued or renewed
cert.revokedCertification revoked
reputation.updatedReputation score changed
compliance.violationCompliance violation detected
federation.peer_addedNew federation peer connected

Creating a Subscription

The server generates a cryptographic secret (32-byte hex) for HMAC signing and returns it in the response. Store this secret securely — it is only shown once.

curl -X POST https://nanda.nexartis.com/api/admin/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nanda_YOUR_KEY" \
  -d '{
    "callbackUrl": "https://your-app.com/hooks/nanda",
    "events": ["agent.registered", "cert.issued"]
  }'

Response:

{
  "id": "sub_abc123",
  "secret": "a1b2c3d4...64-char-hex-string",
  "status": "active"
}

Subscription Lifecycle

Pause / Resume

Temporarily stop deliveries without deleting the subscription. Paused subscriptions retain their secret and event filters.

Circuit Breaker

After 10 consecutive delivery failures, the subscription is automatically disabled. Successful deliveries reset the failure counter. Disabled subscriptions must be manually re-enabled.

Delete

Only the subscription owner can delete. Deletion is permanent — the secret is discarded.

Delivery Envelope

Each delivery POSTs a JSON envelope to your callback URL:

{
  "event": "agent.registered",
  "payload": { "agent_id": "my-agent", "name": "..." },
  "timestamp": "2026-04-05T12:00:00.000Z",
  "idempotency_key": "nk_abc123"
}

Headers

HeaderDescription
X-Webhook-SignatureHMAC-SHA256 signature: sha256={hex_digest}
X-Webhook-EventEvent type string (e.g. agent.registered)
X-Idempotency-KeyUnique key for deduplication
Content-Typeapplication/json

Verifying Signatures

import crypto from 'node:crypto';

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(body).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

URL Validation

Callback URLs are validated at subscription creation:

  • Must use HTTPS — HTTP is rejected
  • Must not target localhost, 127.0.0.1, [::1], or any private/RFC1918 IP range
  • Redirects are blocked during delivery (SSRF protection) — returns are discarded rather than followed

Delivery Behavior

  • Timeout: 10-second delivery timeout per request
  • Success: Any 2xx response resets the failure counter and updates last_delivered_at
  • Failure: Non-2xx or network error increments the failure counter
  • Circuit breaker: ≥ 10 consecutive failures → subscription disabled

API Endpoints

MethodPathDescription
POST/api/admin/webhooksCreate subscription
GET/api/admin/webhooksList subscriptions
DELETE/api/admin/webhooks/:idDelete subscription
PATCH/api/admin/webhooks/:id/pausePause subscription
PATCH/api/admin/webhooks/:id/resumeResume subscription

MCP Integration

Create subscriptions via MCP: nanda_subscribe_webhook tool. Manage existing subscriptions via the /api/admin/webhooks REST endpoints.

See also API Reference for all endpoints · MCP Tools for nanda_subscribe_webhook
Related reading Developer API Keys — authentication and key management for webhook integrations · NestJS Quickstart — deploy and configure a NANDA node with webhook support

Coming Soon

By Invitation Only