Webhooks

Receive real-time event notifications when invoice, payment, transaction, payout, and refund states change.

Use webhooks to keep your system in sync without polling.

Webhook references

Choose a page for the event family you need:

Reference

Payments

Description

Payment session lifecycle events.

Page

Payments

Reference

Invoices

Description

Invoice creation, payment, updates, and expiry.

Page

Invoices

Reference

Transactions

Description

On-chain transaction detection and confirmation.

Page

Transactions

Reference

Payouts

Description

Outgoing payout events.

Page

Payouts

Reference

Refunds

Description

Refund creation, completion, and failure.

Page

Refunds

Before you go live

• Verify the webhook signature on every request.
• Return a 2xx response as soon as you accept the event.
• Use X-CoinCircuit-Delivery-Id to handle retries safely.

Process webhook deliveries asynchronously when possible.

Store the delivery ID and ignore duplicates.

Event flow

Most payment flows follow this order:

1. transaction.received
2. transaction.confirmed
3. One of the payment events
4. Any follow-up invoice, payout, or refund events

Use transaction events for blockchain state.

Use payment and invoice events for business state.

Delivery format

All webhook deliveries are sent as POST requests to your webhook endpoint.

Standard headers

Header	Description
X-CoinCircuit-Event	Event name for the current delivery.
X-CoinCircuit-Delivery-Id	Unique ID for this delivery attempt.
X-CoinCircuit-Signature	HMAC-SHA256 signature for the request body.
X-CoinCircuit-Timestamp	Unix timestamp used during signing.

Retry behavior

If your endpoint does not return a 2xx response, delivery is retried with backoff.

Build handlers to be idempotent.

Use the delivery ID to detect duplicates safely.

Verify signatures

Verify signatures against the raw request body.

Reject invalid requests before you process the payload.

Verify signature

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret, timestamp) {
  try {
    const signedPayload = timestamp ? `${timestamp}.${payload}` : payload;
    const expectedSignature = crypto
      .createHmac('sha256', secret)
      .update(signedPayload, 'utf8')
      .digest('hex');

    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expectedSignature, 'hex')
    );
  } catch (_) {
    return false;
  }
}

Use in an endpoint

const payload = rawBody;
const signature = req.headers['x-coincircuit-signature'];
const timestamp = req.headers['x-coincircuit-timestamp'];
const secret = 'whsec_...';

if (!verifyWebhookSignature(payload, signature, secret, timestamp)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

return res.status(200).json({ received: true });

Use the raw request body for signature verification.

Do not reformat the JSON before calculating the HMAC.

Shared payload shape

Every delivery includes:

• event — the event name
• data — the event payload

The object inside data changes by event family:

• invoice events use data.invoice
• payment events use data.session
• transaction events use data.transaction and data.session
• payout events use data.payout
• refund events use data.refund