Hooks and business events

Current legacy Hooks

The current web hook processor sends the producer’s JSON or form payload. It supplies X-Nucleus-Entity, X-Nucleus-Action, Nucleus-Platform-TenantId and X-Nucleus-Endpoint. This is not the proposed canonical business-event envelope.

Read GET /nucleus/api/v1/hooks/template for supported entity/action combinations and template fields on the selected server. Register through /hooks under its published request schema and staff authority. Payload URL and Content Type are consumed by the inspected processor. The earlier guide’s Secret configuration does not establish signing for these web methods; do not assume a signature will be supplied.

Delivery is asynchronous. The inspected callback logs outcomes; it does not prove durable retry, replay, ordering or exactly-once delivery. Send-time destination checks can refuse delivery without undoing the financial operation. A missing notification is not evidence that the underlying banking action failed.

Target canonical events

The target API/event standard requires immutable event identity, institution and aggregate identity/version, event type/schema version, source time/business date, correlation/causation and minimal typed payload. Subscriptions bind approved event types, destination ownership and signing keys. Delivery is at least once; consumers deduplicate by event ID and handle sequence gaps using authoritative state/replay.

Delivery attempts have their own IDs and retry state. Dead-letter items remain owned. Replay preserves original event identity and does not automatically regenerate external financial actions or customer communications. Key rotation, signature verification, bounded timestamp tolerance and invalid-signature handling must be qualified before use.

These are proposed requirements, not guarantees of legacy Hooks. See repository contracts reference/flows/API_EVENT_IDEMPOTENCY_STANDARD.md, reference/contracts/CURRENT_API_SURFACE.md and reference/experience/09_DEVELOPER_EXPERIENCE.md for source evidence and target lifecycle.