Webhooks

Receive push notifications when new filings are published on EDINET 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 EDINET.

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.