> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/webhooks/readme.md).

# Webhooks

Receive real-time event notifications for payments, invoices, transactions, payouts, refunds, swaps, and deposits.

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

Use webhooks to keep your system in sync without polling.

### Webhook references

Choose a page for the event family you need:

<table data-view="cards"><thead><tr><th>Reference</th><th>Description</th><th data-card-target data-type="content-ref">Page</th></tr></thead><tbody><tr><td>Payments</td><td>Payment session lifecycle events.</td><td></td></tr><tr><td>Invoices</td><td>Invoice payment, updates, and expiry.</td><td></td></tr><tr><td>Transactions</td><td>On-chain transaction detection and confirmation.</td><td></td></tr><tr><td>Payouts</td><td>Outgoing payout events.</td><td></td></tr><tr><td>Refunds</td><td>Refund creation, completion, and failure.</td><td></td></tr><tr><td>Swaps</td><td>Currency swaps between your balances.</td><td></td></tr><tr><td>Deposits</td><td>Crypto and bank transfer deposits into your account.</td><td></td></tr></tbody></table>

### Before you go live

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

{% hint style="info" %}
Process webhook deliveries asynchronously when possible.

Store the delivery ID and ignore duplicates.
{% endhint %}

### 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, such as `transaction.confirmed`.     |
| `X-CoinCircuit-Delivery-Id` | Unique ID for this delivery.                     |
| `X-CoinCircuit-Signature`   | HMAC-SHA256 signature of the request body.       |
| `X-CoinCircuit-Timestamp`   | Unix timestamp of the delivery, used in signing. |

#### Retry behavior

If your endpoint returns anything other than a `200`, the delivery is retried with exponential backoff, roughly at 0 minutes, 1 minute, 10 minutes, then 1 hour.

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.

{% tabs %}
{% tab title="Verify signature" %}

```javascript
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;
  }
}
```

{% endtab %}

{% tab title="Use in an endpoint" %}

```javascript
const payload = rawBody;
const signature = req.headers['x-coincircuit-signature'];
const timestamp = req.headers['x-coincircuit-timestamp'];
const secret = process.env.COINCIRCUIT_WEBHOOK_SECRET;

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

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

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Use the raw request body for signature verification.

Do not reformat the JSON before calculating the HMAC.
{% endhint %}

### Shared payload shape

Every delivery includes:

* `event`: the event name
* `data`: the event payload

The object inside `data` changes by event family:

* payment events use `data.session`
* invoice events use `data.invoice` and `data.payments`
* transaction events use `data.transaction` and `data.session`
* payout events use `data.payout`
* refund events use `data.refund`
* swap events use `data.swap`
* deposit events put the deposit directly in `data`
