BaZi API Webhooks — Event-Driven
Four Pillars Data Streams
Stop polling. Stream real-time Chinese calendar shifts, solar term transitions, and quota events directly to your microservices with cryptographic HMAC SHA-256 verification.
Supported Webhook Event Topics
Configure fine-grained subscription filters to receive only the calendar events your application requires.
Daily Pillar Transition
Triggered automatically at the onset of each new day pillar. Ideal for mobile calendar pushes, daily almanac updates, and biorhythm recalculations.
24 Solar Term Shift
Fired the exact minute the solar longitude hits 15-degree astronomical increments (e.g. Li Chun, Chun Fen, Dong Zhi), marking month pillar shifts.
Usage Quota Alerts
Automatic ops alerts dispatched when your monthly API consumption crosses 80% and 100% thresholds, preventing silent downtime.
Verify Signatures in Node.js
Prevent replay attacks and spoofing. Verify every incoming webhook using the signature in the x-bazi-signature header:
import crypto from "crypto";
export function verifyBaziWebhook(
rawBody: string,
signatureHeader: string,
webhookSecret: string
): boolean {
const expectedSignature = crypto
.createHmac("sha256", webhookSecret)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signatureHeader),
Buffer.from(expectedSignature)
);
}Sample Webhook Event Payload
Every event contains an immutable ID, RFC3339 timestamp, event topic, and contextual data object:
{
"id": "evt_live_8f3a19b2c",
"event": "solar_term.changed",
"timestamp": "2026-09-23T01:05:00Z",
"data": {
"solarTerm": "Autumn Equinox (秋分)",
"solarLongitude": 180,
"effectivePillar": {
"month": "Ding You (丁酉)"
},
"metadata": {
"timezone": "UTC"
}
}
}Enterprise-Grade Delivery Infrastructure
Automated 3x Retries
Exponential backoff at 1m, 5m, and 15m intervals protects against temporary subscriber outages.
Replay Attack Protection
Timestamps and cryptographic hashes ensure expired or intercepted payloads cannot be re-executed.
Dead Letter Logging
Inspect failed deliveries, HTTP response status codes, and latency diagnostics directly in dashboard.
Webhook FAQs
Frequently asked questions about webhook setup and security.
Which subscription plans support Outbound Webhooks?
Outbound Webhooks are available on the Pro plan (up to 3 active webhook endpoints) and Premium plan (up to 10 active endpoints). You can configure endpoint URLs and secret signing keys directly from your developer dashboard.
How are webhook payloads authenticated?
Every outbound HTTP POST request includes an 'x-bazi-signature' header containing an HMAC-SHA256 hex digest of the raw request body, calculated using your webhook secret. This guarantees payload integrity and authenticates the sender.
What events can trigger a webhook dispatch?
Supported event topics include 'daily.bazi_shift' (fired at midnight local solar time), 'solar_term.changed' (triggered when the sun enters a new 24 Solar Term degree mark), and 'usage.threshold_reached' (notifying you when your API monthly quota reaches 80% or 100%).
What is the retry schedule if my endpoint fails to respond?
If your receiving server does not return an HTTP 2xx status code within 5 seconds, our webhook delivery worker automatically initiates an exponential backoff retry schedule: 1st retry after 1 minute, 2nd retry after 5 minutes, and 3rd retry after 15 minutes.
Connect Real-Time Four Pillars Webhooks
Upgrade to Pro or Premium to register your webhook endpoints and stream calendar events today.