Webhook events

Every signed lifecycle event and its payload shape, as verified and typed by pulse.webhooks.verify / verifyOnce.

Every delivery is signed (Pulse-Signature, HMAC-SHA256 over the raw body), at-least-once, and carries an evt_* id for de-duplication. pulse.webhooks.verify / verifyOnce return the typed WebhookEvent. See Webhooks for the handler pattern and the node reference for the method signatures.

This surface reflects the @pulsebyshiga/node types — the working view of the API until the canonical Pulse OpenAPI contract is published. Wire shapes (snake_case JSON, decimal-string amounts) are stable; a few fields are still being reconciled and are flagged where they appear.

Envelope

Every event shares this envelope; only type and the data shape differ.

id · string

evt_* — the idempotency key for consumers.

type · WebhookEventType

The event name (the ## headings below).

created_at · string

data · object

Event-specific payload, documented per event below.

Credit a customer only after a verified disbursement.completed event — never off a client callback. See Webhooks.

collection.order.created

data.order · CollectionOrder

The full order (see CollectionOrder).

collection.deposit.detected

data.order_id · string

data.deposit · Deposit

Show Deposit

tx_hash · string

amount · string

On-chain detected amount — the credited figure, never the quoted one.

asset · "USDC" | "USDT"

network · Network

detected_at · string

confirmed_at · string | null

collection.deposit.confirmed

data.order_id · string

data.deposit · Deposit

Same Deposit shape as collection.deposit.detected; confirmed_at is now set.

collection.deposit.wrong_chain

Provisional contract shape (PRD wrong-chain row) — the real detection signal comes from Pulse and the recovery policy is still being decided. Treat as subject to change until the canonical contract publishes.

data.order_id · string

data.deposit · WrongChainDeposit

Show WrongChainDeposit

tx_hash · string

amount · string

asset · "USDC" | "USDT"

network · string

Network the funds actually arrived on (may be outside the supported set).

detected_at · string

data.expected_network · Network

The network the order expected payment on.

collection.amount.underpaid

data.order_id · string

data.expected · string

Expected amount, decimal string.

data.received · string

Received amount, decimal string.

data.asset · "USDC" | "USDT"

data.network · Network

data.tx_hash · string

collection.amount.overpaid

data · AmountMismatchData

Same shape as collection.amount.underpaid: order_id, expected, received, asset, network, tx_hash.

collection.order.expired

data.order_id · string

collection.order.failed

data.order_id · string

data.reason · string

disbursement.completed

The only event you should credit a customer from.

data.order_id · string

data.disbursement · Disbursement

Show Disbursement

settlement_ref · string

currency · "NGN" | "USD"

amount · string

virtual_account_ref · string | null

Naira gate only; null for USD (partner omnibus).

completed_at · string