Skip to main content
Webhooks let your server react to events the moment they happen on-chain — without polling the API. When a payment is confirmed, an escrow is locked, or a stream runs dry, FlareHQ sends an HTTP POST to your registered endpoint with a signed JSON payload describing the event. This page explains how to register your endpoint, verify every delivery, and handle each event type correctly.

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 an event 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 an event 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

Outbound notifications to your webhookUrl are currently sent as unsigned, fire-and-forget POSTs (Content-Type: application/json, no signature header, no automatic retries). Do not treat an incoming POST as proof of payment. Always re-verify the referenced entity server-side — GET /api/payments/verify/{reference} for payments, GET /api/escrow/status?reference=... for escrows — before fulfilling orders or releasing goods.
The examples below show the recommended handler shape once signature verification is available. Until signed deliveries land, the constructEvent calls are aspirational — keep the re-verification step regardless.
Verify signatures against the raw request body bytes, not a parsed or re-serialized JSON object. Even a single whitespace difference will cause the HMAC to fail. See the examples below for how to read the raw body correctly in each framework.

Express

src/app/api/webhooks/route.ts

Next.js App Router

src/app/api/webhooks/route.ts

Retry Policy

The current product sends each notification once with no automatic retries and no dashboard event-log replay — a fetch failure is logged server-side only. Design your integration to reconcile by polling GET /api/payments/verify/{reference} (payments) or GET /api/escrow/status (escrows) rather than depending on redelivery. The retry schedule below describes the intended behaviour, not current behaviour.
If your endpoint returns anything other than a 2xx 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

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.
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.
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.
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.