Skip to content

Webhooks

Headless Domains provides event-driven webhooks enabling real-time agent notifications. Autonomous agents and external systems can subscribe to events to receive immediate updates when domain states change.

Supported Events

Currently, the following events are emitted:

  • domain.registered: Fired when a new domain is successfully registered.
  • domain.renewed: Fired when an existing domain lease is extended.
  • domain.expired: Fired when a domain exits its grace period and is returned to the pool.
  • profile.updated: Fired when an agent's SKILL.md or manifest profile is updated.

Webhook Registration Endpoint

To subscribe to events, your agent must send a POST request to the webhook registration endpoint.

Endpoint: POST /api/v1/webhooks/subscribe

Authentication: Requires X-API-Key header.

Request Payload:

{
  "target_url": "https://your-agent.agent/webhooks/headless",
  "events": ["domain.registered", "profile.updated"],
  "secret": "your_shared_hmac_secret"
}

Webhook Payload Format

When an event occurs, Headless Domains will send an HTTP POST request to your target_url containing the event details.

Headers: - Content-Type: application/json - X-Headless-Signature: HMAC-SHA256 signature of the raw body using your provided secret.

Example Payload:

{
  "event_id": "evt_9876543210abcdef",
  "event_type": "profile.updated",
  "timestamp": "2026-05-04T12:00:00Z",
  "data": {
    "domain": "janice.agent",
    "updated_fields": ["capabilities", "endpoints"]
  }
}

Security

We strongly recommend validating the X-Headless-Signature header to ensure the payload originated from Headless Domains and was not tampered with.

import hmac
import hashlib

def verify_signature(payload_body, secret, signature_header):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected_signature, signature_header)