[ Switch to styled version → ]

← Docs index

Webhooks

The daemon sends real-time HTTP POST notifications for events. Events are delivered asynchronously to a configured webhook URL.

Overview

When configured, the daemon POSTs a JSON event to a webhook URL for events such as connections, trust changes, messages received, and pub/sub activity. Events are delivered asynchronously. If the endpoint is unavailable, events are dropped.

Configuration

Set the webhook at daemon startup:

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

Set the webhook 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 'webhook' and 'applied' (boolean).

Clear the webhook:

pilotctl clear-webhook

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

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

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

Event types

Node lifecycle events:

• node.registered - Daemon registered with the registry
• node.reregistered - Re-registration after keepalive timeout
• node.deregistered - Daemon deregistered from the registry
• 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
• 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.established - Tunnel handshake completed
• tunnel.relay_activated - Relay fallback activated for a peer (symmetric NAT)

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)
• 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

Every webhook POST contains a JSON body with this 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"
  }
}

Payload fields:

• 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. It is null for events with no additional payload.

Example receiver

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. The new URL takes effect immediately.

# 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, so it survives daemon restarts.