Webhooks deliver event notifications to your server via HTTP POST. Use them for server-side order fulfillment instead of relying on polling alone.

Event types

Event	Description
`invoice.activated`	Draft invoice became payable
`invoice.confirming`	Payment detected, awaiting blockchain confirmations
`invoice.draft_expired`	Draft invoice expired before activation
`invoice.paid`	Invoice payment is fully paid and confirmed
`invoice.overpaid`	Customer sent more than the requested amount
`invoice.underpaid`	Customer sent less than the requested amount
`invoice.sent`	Invoice notification email was sent
`invoice.expired`	Invoice expired without sufficient payment
`invoice.invalid`	Invoice marked invalid
`invoice.late_deposit`	Deposit received after invoice expiry
`invoice.deposit_reversed`	Confirmed deposit reversed
`balance.credited`	Merchant balance was credited and is spendable
`payout.completed`	Payout confirmed on-chain
`payout.failed`	Payout failed and reserved funds were released
`test`	Dashboard test delivery event

Delivery

Method: POST with JSON body
Retries: Up to 10 attempts with exponential backoff
Timeout: Your endpoint should respond within 15 seconds
Success: Any 2xx status code is treated as successful delivery

Webhook delivery is at least once. balance.credited includes event_id; invoice and payout handlers should de-duplicate by event type plus the invoice, payout, or payment IDs in data.

Headers

Every webhook request includes:

X-Halfin-Signature: t=1735689900,v1=5d41402abc4b2a76b9719d...
X-Halfin-Event: invoice.paid
Content-Type: application/json

Setup

Open dashboard webhooks

Go to Settings -> Webhooks in the halfin dashboard.

Add your endpoint URL

Paste your HTTPS endpoint that will receive events.

Select the event types you care about. Use invoice.paid to track payment confirmation and balance.credited to fulfill orders from spendable merchant balance.

Payload schemas

For the generated JSON schema of each webhook event payload, see the Webhook Schemas section.

For converted payments, invoice.paid can arrive while settlement is still in progress. Fulfill from balance.credited, which fires only after the target balance is credited or the payment is terminally credited in the source asset.

Webhooks