Create a webhook subscription to watch UK companies for changes.

Registrum checks each watched company roughly every 15 minutes. When a change is detected (e.g., status becomes dissolved, accounts go overdue), a signed POST is delivered to your URL.

Supported events:

• status_change - company_status changes (e.g., active → dissolved)
• accounts_overdue - accounts filing deadline missed
• confirmation_overdue - confirmation statement deadline missed
• directors_changed - a director is appointed or resigned (checked every 6 hours)
• pscs_changed - a PSC is added, ceased, or their ECCTA verification status changes (every 6 hours)
• compliance_risk_changed - the company's overall ECCTA risk rating changes, e.g., compliant → partial (every 6 hours). Requires Pro/Enterprise or the Compliance Monitoring add-on.

Webhook watch caps - the number of distinct companies you can watch across all your webhooks (existing + this request combined), by plan:

Exceeding your cap, or requesting compliance_risk_changed without Pro/Enterprise, returns 403 PLAN_REQUIRED. The Compliance Monitoring add-on raises your cap to 100 companies and unlocks compliance_risk_changed on any plan.

Payload delivered to your URL:

{
  "event": "company_updated",
  "company_number": "00445790",
  "changes": {
    "status_change": {"from": "active", "to": "dissolved"}
  },
  "triggered_at": "2026-03-11T10:00:00Z"
}

Verifying signatures: Every delivery includes an X-Registrum-Signature: sha256=<hex> header. Verify it with HMAC-SHA256 using the secret returned at creation time:

import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), request.body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers["X-Registrum-Signature"])

Note: The secret is returned once at creation - store it securely.

{
  "company_numbers": [
    "00445790"
  ],
  "events": [
    "status_change",
    "accounts_overdue"
  ],
  "url": "https://yourapp.example.com/hooks/registrum"
}

{
  "cache_age_seconds": 3421,
  "cached": true,
  "credits_remaining": 487,
  "credits_used": 1,
  "data": {
    "company_age_years": 78,
    "company_name": "TESCO PLC",
    "company_number": "00445790",
    "company_status": "active",
    "company_type": "plc"
  },
  "data_source": "cached",
  "status": "success"
}