[ Switch to styled version → ]

← Docs index

Webhooks

The daemon can send real-time HTTP POST notifications for events. This document describes the configuration, event types, and payload format for webhooks.

Overview

When a webhook URL is configured, the daemon sends a JSON event via HTTP POST for events such as connections, trust changes, messages, and pub/sub activity. Events are delivered asynchronously. If the endpoint is unavailable, events are dropped without being queued.

Configuration

A webhook can be configured at daemon startup.

pilotctl daemon start --webhook http://localhost:8080/events

A webhook can be set at runtime.

pilotctl set-webhook http://localhost:8080/events

This command persists the URL to ~/.pilot/config.json and applies it to the running daemon. It returns the webhook URL and an 'applied' boolean indicating if the running daemon accepted the change.

To clear a webhook:

pilotctl clear-webhook

This removes the webhook URL from the configuration and the running daemon. It returns the cleared webhook URL and an 'applied' boolean.

The webhook URL can also be set directly in ~/.pilot/config.json.

{
  "registry": "34.71.57.205:9000",
  "beacon": "34.71.57.205:9001",
  "webhook": "http://localhost:8080/events"
}

Event types

Daemon & node lifecycle events:

• daemon.shutting_down: Daemon is shutting down (final pre-exit event)
• node.registered: Daemon registered with the registry
• node.reregistered: Re-registration after keepalive timeout
• agent.registered: An agent client (driver) attached to this daemon
• agent.heartbeat: Periodic heartbeat from an attached agent client
• key.rotated: Daemon's Ed25519 keypair was rotated
• network.auto_joined: Daemon auto-joined a network on startup

Connection events:

• conn.syn_received: Incoming connection request
• conn.established: Connection fully established
• conn.fin: Connection closed gracefully (FIN)
• conn.rst: Connection reset
• conn.idle_timeout: Connection timed out due to inactivity
• conn.dead_peer: Keepalive probes failed; peer declared dead
• conn.accept_queue_full: Accept queue overflowed — connection dropped before processing
• syn.rejected: Incoming SYN rejected (untrusted source)
• syn.port_rejected: Incoming SYN rejected by network policy

Tunnel events:

• tunnel.peer_added: New tunnel peer discovered
• tunnel.relay_activated: Relay fallback activated for a peer (symmetric NAT)
• tunnel.desync_salvage: Tunnel key desync detected and salvaged via re-handshake

Trust & handshake events:

• handshake.received: Trust handshake request received from a peer
• handshake.pending: Handshake queued for approval
• handshake.approved: Handshake approved (by you)
• handshake.rejected: Handshake rejected (by you)
• handshake.auto_approved: Mutual handshake - auto-approved
• trust.revoked: Trust revoked locally (you untrusted a peer)
• trust.revoked_by_peer: Trust revoked by a remote peer

Data events:

• message.received: Typed message received via data exchange (port 1001)
• file.received: File received via data exchange (port 1001) — buffered into ~/.pilot/received/
• file.delivered: File send completed end-to-end (sender-side)
• data.datagram: Datagram received
• datagram.rejected: Datagram rejected (untrusted source)
• datagram.port_rejected: Datagram rejected by network policy

Pub/Sub events:

• pubsub.subscribed: Subscriber joined a topic
• pubsub.unsubscribed: Subscriber left a topic
• pubsub.published: Event published to a topic

Security events:

• security.syn_rate_limited: SYN rate limiter triggered
• security.nonce_replay: Nonce replay detected (potential attack)

Policy & Managed events:

• policy.cycle: Policy evaluation cycle completed
• managed.cycle: Managed network evaluation cycle completed

Payload format

Each webhook POST contains a JSON body with the following structure.

{
  "event_id": 1,
  "event": "handshake.received",
  "node_id": 5,
  "timestamp": "2026-01-15T12:34:56.789Z",
  "data": {
    "peer_node_id": 7,
    "justification": "want to collaborate"
  }
}

• event_id (uint64): Monotonically increasing event counter, unique per daemon lifetime.
• event (string): The event type.
• node_id (uint32): The ID of the node emitting the event.
• timestamp (string): ISO 8601 timestamp.
• data (object): Event-specific data. This is null for events with no additional payload.

Example receiver

This is a minimal webhook receiver in Python.

#!/usr/bin/env python3
# webhook_receiver.py
from http.server import HTTPServer, BaseHTTPRequestHandler
import json

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length", 0))
        body = json.loads(self.rfile.read(length))

        event = body["event"]
        data = body.get("data", {})

        if event == "handshake.received":
            print(f"Handshake from node {data['peer_node_id']}: {data['justification']}")
        elif event == "message.received":
            print(f"Message from {data['from']}: {data['type']}")
        elif event == "file.received":
            print(f"File received: {data['filename']} ({data['size']} bytes)")
        else:
            print(f"Event: {event}")

        self.send_response(200)
        self.end_headers()

    def log_message(self, *args):
        pass  # suppress request logs

HTTPServer(("", 8080), Handler).serve_forever()

# Start the receiver, then configure the webhook:
python3 webhook_receiver.py &
pilotctl set-webhook http://localhost:8080/events

Runtime hot-swap

The webhook URL can be changed while the daemon is running, and the new URL takes effect immediately without a restart.

# Switch to a new endpoint
pilotctl set-webhook http://localhost:9090/v2/events

# Disable webhooks temporarily
pilotctl clear-webhook

# Re-enable
pilotctl set-webhook http://localhost:8080/events

The webhook URL is persisted to ~/.pilot/config.json and survives daemon restarts.