Register a Webhook Endpoint
1
Open Webhook Settings
In the FlareHQ Dashboard, navigate to Settings › Webhooks and click Add Endpoint.
2
Enter Your HTTPS URL
Provide the public HTTPS URL of your handler (for example,
https://yourdomain.com/api/webhooks). FlareHQ will not deliver to HTTP or localhost URLs in production.3
Save Your Webhook Secret
After saving, copy the Webhook Secret shown on the endpoint detail page. You will use this secret to verify that every incoming request genuinely originates from FlareHQ. Store it in your environment variables:
.env.local
4
Select Events (Optional)
By default your endpoint receives all events. Use the event filter to subscribe only to the types relevant to your integration.
There is no webhook-registration endpoint in the current API — you attach a
webhookUrl to each payment, escrow, stream, scheduled-payment, or payroll request, and FlareHQ POSTs that event’s notification to the URL you supplied. Inbound platform webhooks live at POST /api/webhooks/circle (Circle, x-circle-signature) and POST /api/telegram/webhook (Telegram secret token).Webhook Events
Every event FlareHQ can emit is listed below. Each delivery POSTs a flat JSON object headed by anevent string and the payment/escrow/stream reference, followed by type-specific fields.
payment.settled
A payment has been settled — USDC confirmed at a checkout session or via CCTP. Payload includes
reference, amount, currency, status (SUCCESS), arcTxHash, and explorerUrl.payment.auto_settled
A CCTP V2 inbound transfer was detected and automatically routed to Arc and minted. Payload includes
reference, arcTxHash, amount, settlementType (CCTP_V2_AUTO_ROUTED), and explorerUrl.escrow.created
A new escrow contract has been deployed and funded on Arc. Payload includes
reference, amount, currency, and the on-chain txHash.escrow.released
Escrowed funds have been released to the beneficiary. Payload includes
reference, amount, currency, and releaseTxHash.escrow.disputed
A dispute has been raised against an active escrow; funds are frozen. Payload includes
reference, amount, disputedBy, reason, and txHash.dispute.resolved
A FlareHQ admin has resolved a dispute on-chain. Payload includes the escrow
reference, outcome, and resolveTxHash.refund.completed
An expired escrow has been refunded to the depositor. Payload includes
reference, amount, and txHash.stream.created
A new payment stream has been started. Payload includes
reference, senderSCA, receiverSCA, ratePerSecond, totalDeposited, and estimatedDurationSeconds.stream.stopped
A stream was manually stopped before it fully drained. Payload includes
reference, totalStreamed, refundedToSender, and txHash.stream.withdrawn
A receiver withdrew accrued USDC from an active stream. Payload includes
reference, receiverSCA, amountWithdrawn, and totalStreamed.stream.completed
A stream has fully drained — all funds have been delivered to the recipient. Payload includes
reference, receiverSCA, amountWithdrawn, and totalStreamed.payroll.completed
A payroll batch finished processing. Payload includes
batchRef, status (COMPLETED/PARTIAL_FAILURE/FAILED), and per-recipient results.Webhook Event Object Shape
Every delivery has a consistent top-level shape regardless of event type. The payload is a flat object headed by anevent string and the entity reference, followed by type-specific fields:
string
required
The event type string, for example
payment.settled, escrow.released, or stream.created.string
required
The reference of the affected entity — an
arc_ref_... payment, stream_... stream, or escrow reference. Use it to correlate the event with your records and, for payments, with GET /api/payments/verify/.string
Link to the on-chain transaction on the Arc explorer (
https://explorer.arc.io for production Mainnet; https://explorer.arc.io for Arc Mainnet development) for events that include a settlement transaction (payment.settled, escrow.*, stream.*, refund.completed).object
required
Additional type-specific fields accompany the head — for example
amount/currency/arcTxHash for payment.settled, ratePerSecond/totalDeposited for stream.created, or batchRef/results for payroll.completed. Refer to the event cards above for the key fields in each payload.Verifying webhook deliveries
The examples below show the recommended handler shape once signature verification is available. Until signed deliveries land, theconstructEvent calls are aspirational — keep the re-verification step regardless.
Express
src/app/api/webhooks/route.ts
Next.js App Router
src/app/api/webhooks/route.ts
Retry Policy
If your endpoint returns anything other than a2xx status — or times out after 30 seconds — FlareHQ will retry delivery automatically:
After three failed attempts the event is marked as undelivered. You can inspect and manually replay undelivered events from Settings › Webhooks › Event Log in the Dashboard.
Best Practices
Respond 200 before processing
Respond 200 before processing
Return a
200 OK response as quickly as possible — ideally before doing any database writes or downstream API calls. If your handler takes too long, FlareHQ will treat it as a timeout and schedule a retry. Enqueue the event to a background job queue and acknowledge receipt immediately.Deduplicate using the event ID
Deduplicate using the event ID
Network retries mean your handler may receive the same event more than once. Store the
event.id in your database when you process an event and skip any delivery whose ID you have already recorded.Log everything during development
Log everything during development
While you are building, log the full event object for every delivery. This makes it much easier to understand what fields are available for each event type before you write your business logic.
Use environment-specific secrets
Use environment-specific secrets
Keep a separate webhook secret for testnet and production. This way a misconfigured staging integration can never accidentally pollute production data.
Next Steps
SDKs
Install and configure the FlareHQ SDK for Node.js, React, or Python.
Errors & Troubleshooting
Understand error codes and resolve common delivery failures.
Escrow & Disputes
Learn how escrow and dispute events map to on-chain contract state.
Streaming Payments
Understand how stream lifecycle events fire as funds drip on-chain.

