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.confirming`	Payment detected, awaiting blockchain confirmations
`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.expired`	Invoice expired without sufficient payment
`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

The dashboard Send Test action sends a test delivery to active webhook endpoints in the selected environment. test is not a subscribable business 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.

Copy the webhook secret

Use it for signature verification.

Payload schemas

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

Use invoice.paid to track payment confirmation. Use balance.credited when fulfillment depends on spendable merchant balance availability.

Webhooks

On this page