Webhooks

Receive push notifications when new filings hit the public record or ownership signals are detected. Register a URL, choose which events to subscribe to, and verify payloads with your signing secret.

Register a Webhook

Send a POST request to /v1/webhooks with your target URL and the events you want to receive. The URL must use HTTPS and resolve to a public IP address.

POST /v1/webhooks

curl "https://api.axiora.dev/v1/webhooks" \
  -H "Authorization: Bearer ax_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/axiora",
    "events": ["new_filing", "amendment"]
  }'

The response includes a secret. a 64-character hex string used to verify webhook signatures:

Response · 201 Created

{
  "data": {
    "id": 1,
    "url": "https://example.com/webhooks/axiora",
    "events": ["amendment", "new_filing"],
    "active": true,
    "secret": "a1b2c3d4e5f6...64 hex characters",
    "created_at": "2026-02-24T10:00:00Z"
  },
  "meta": { "request_id": "req_abc123def456" }
}

Important: The secret is only returned once, when the webhook is created. Store it securely. it cannot be retrieved later.

Available Events

Subscribe to one or more of the following event types:

EventFired when

new_filingA new securities report (annual, semi-annual, or quarterly) is ingested from the public record.

amendmentAn amendment to a previously filed report is published.

correctionA correction to a previously filed report is published.

ownership.accumulationAn ownership accumulation signal is detected (streak of stake increases, large step-up, or pace acceleration).

ownership.exitAn ownership exit signal is detected (stake drops below 5% or large step-down).

ownership.activistAn activist escalation is detected (purpose change to important proposal or activist-related signals).

ownership.new_positionA new large shareholding position is first reported (initial 5%+ filing).

Every delivery sends a JSON body with filing or signal data. The event type is sent in the X-Axiora-Event header:

Payload

{
  "doc_id": "S100ABCD",
  "edinet_code": "E02144",
  "name_jp": "トヨタ自動車株式会社",
  "fiscal_year": 2025,
  "accounting_standard": "IFRS",
  "doc_type": "120",
  "fields_count": 25
}

Signature Verification

Every webhook delivery includes an HMAC-SHA256 signature so you can verify it came from Axiora and was not tampered with. The signature is computed over the raw request body using your webhook secret.

HeaderDescription

X-Axiora-Webhook-SignatureHMAC-SHA256 hex digest of the request body, signed with your webhook secret

X-Axiora-EventThe event type (e.g. new_filing, amendment, correction)

Content-Typeapplication/json

To verify a delivery:

Read the raw request body as bytes (do not parse it first).
Compute HMAC-SHA256 of the body using your webhook secret as the key.
Compare the result to the X-Axiora-Webhook-Signature header using a constant-time comparison.

Python:

Python

import hmac, hashlib

def verify_webhook(payload: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Node.js:

Node.js

const crypto = require("crypto");

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

Delivery Behavior

Webhook URLs must use HTTPS. Private/internal IPs are blocked (SSRF protection).
Each delivery attempt has a 10-second timeout.
Failed deliveries are retried up to 2 times with exponential backoff (1s, 2s). 3 attempts total.
A delivery is considered successful if your endpoint returns a 2xx status code.