> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/core-concepts-webhooks/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Webhooks

> Learn how to use webhooks to receive real-time notifications about events in your payment processing with CrissCross.

### Overview

CrissCross uses webhooks to notify your application about events that occur within your payment processing. These notifications are delivered via HTTP POST requests to your specified endpoint, allowing you to automate workflows and keep your systems synchronized with payment activities.

CrissCross sends events for transactions, refunds, payouts, payout beneficiaries, and rate locks. For the full catalogue, the body each event carries, and example payloads, see [Webhook Events](/webhook-events).

This page covers the mechanics: subscribing an endpoint, verifying signatures, and how delivery, retries, and replay behave.

### Getting Started with Webhooks

To integrate webhooks into your application, follow these steps:

1. **Create a webhook subscription** - Configure the HTTPS URL where you want to receive notifications
2. **Implement signature verification** - Verify webhook authenticity using the provided secret
3. **Process webhooks idempotently** - Handle webhook events while avoiding duplicate processing
4. **Acknowledge receipt** - Return HTTP 200 response for successful webhook receipt

### Creating a Webhook Subscription

You can create and configure your webhook subscriptions from the webhooks section of your CrissCross dashboard.

1. Open the webhooks dashboard
2. Click "Add Endpoint"
3. Enter your HTTPS endpoint URL
4. Select the events you want to subscribe to
5. Save your webhook configuration

If you don't see the webhooks section in your dashboard, contact your CrissCross account manager.

### Securing Webhooks

Every webhook delivered by CrissCross includes a signature header that you should verify before processing the event. Signatures are HMAC-SHA256 over the message ID, timestamp, and raw payload.

The example below uses the open-source [`svix`](https://www.npmjs.com/package/svix) npm package, which implements the same signature scheme. If you'd rather not pull in a dependency, see [Manual Webhook Verification](#manual-webhook-verification) further down for a hand-rolled equivalent.

```javascript
import { Webhook } from "svix";
import bodyParser from "body-parser";

const secret = "YOUR_WEBHOOK_SECRET"; // From subscription creation

app.post(
  "/webhooks",
  bodyParser.raw({ type: "application/json" }),
  async (req, res) => {
    const payload = req.body;
    const headers = req.headers;

    const wh = new Webhook(secret);
    let msg;
    
    try {
      msg = wh.verify(payload, headers);
    } catch (err) {
      return res.status(400).json({
        message: err.toString()
      });
    }

    const transaction = JSON.parse(payload);

    // Deduplicate on svix-id: the same delivery may arrive more than once,
    // and two copies can arrive concurrently. Claim the id with a single
    // atomic write — e.g. an INSERT with a unique key on svix-id — before
    // any side effect. A separate check-then-mark leaves a race where both
    // copies pass the check and process the event twice.
    if (!(await claimDelivery(headers["svix-id"]))) {
      return res.json({ received: true }); // another delivery holds the claim
    }

    try {
      // This endpoint is subscribed to transaction.* only, so the payload's
      // status is enough to route within that lifecycle. Subscribe a separate
      // endpoint for payout.* and refund.* — status alone cannot tell them
      // apart from a payment.
      switch (transaction.status) {
        case 'COMPLETED':
          await handleTransactionCompleted(transaction);
          break;
        case 'FAILED':
          await handleTransactionFailed(transaction);
          break;
        // Handle other statuses
      }
    } catch (err) {
      // Release the claim and return a non-2xx so the delivery is retried.
      await releaseDelivery(headers["svix-id"]);
      return res.status(500).json({ received: false });
    }

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

### Manual Webhook Verification

If you'd prefer not to use the `svix` library, you can verify webhook signatures manually with any HMAC-SHA256 implementation. Here's how it works:

#### 1. Required Headers

Each webhook includes three critical headers:

* `svix-id`: Unique identifier for the webhook message
* `svix-timestamp`: Timestamp in seconds since epoch
* `svix-signature`: Base64 encoded list of signatures (space delimited)

#### 2. Constructing the Signed Content

Concatenate the ID, timestamp, and payload with periods:

```javascript
const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
```

> ⚠️ Important: Use the raw request body. Any modification (even whitespace) will invalidate the signature.

#### 3. Calculating the Signature

Use HMAC-SHA256 to verify the signature:

```javascript
const crypto = require('crypto');

function verifyWebhook(payload, headers, secret) {
  const svix_id = headers['svix-id'];
  const svix_timestamp = headers['svix-timestamp'];
  const svix_signature = headers['svix-signature'];

  // Construct the signed content
  const signedContent = `${svix_id}.${svix_timestamp}.${payload}`;
  
  // Extract and decode the secret
  const secretBytes = Buffer.from(secret.split('_')[1], "base64");
  
  // Calculate expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secretBytes)
    .update(signedContent)
    .digest('base64');

  // Get received signatures (can be multiple)
  const receivedSignatures = svix_signature.split(' ').map(sig => {
    // Remove version prefix (e.g., "v1,")
    return sig.split(',')[1];
  });

  // Verify if any signature matches
  return receivedSignatures.includes(expectedSignature);
}
```

#### 4. Timestamp Verification

Always verify the timestamp to prevent replay attacks:

```javascript
function isTimestampValid(timestamp, toleranceInSeconds = 300) {
  const now = Math.floor(Date.now() / 1000);
  return Math.abs(now - timestamp) <= toleranceInSeconds;
}
```

#### Example Implementation

Here's a complete example combining all verification steps:

```javascript
function verifyAndProcessWebhook(req, res) {
  const secret = process.env.WEBHOOK_SECRET;
  const payload = req.body;
  const headers = req.headers;

  try {
    // 1. Verify timestamp
    if (!isTimestampValid(headers['svix-timestamp'])) {
      return res.status(400).json({ error: 'Invalid timestamp' });
    }

    // 2. Verify signature
    if (!verifyWebhook(payload, headers, secret)) {
      return res.status(400).json({ error: 'Invalid signature' });
    }

    // 3. Process webhook
    const event = JSON.parse(payload);
    processWebhookEvent(event);

    res.json({ received: true });
  } catch (err) {
    res.status(400).json({ error: err.message });
  }
}
```

> 🔒 Security Note: Always use constant-time string comparison when comparing signatures to prevent timing attacks.

### Best Practices

1. **Verify Signatures**
   * Always verify webhook signatures using your webhook secret
   * Reject requests with invalid signatures

2. **Handle Events Idempotently**
   * Deduplicate on the `svix-id` header, which uniquely identifies each delivery
   * Store the `svix-id` values you have processed and skip repeats

3. **Implement Proper Error Handling**
   * Return 2xx status codes for successful receipt
   * Return 4xx for invalid requests
   * Return 5xx for processing errors

4. **Monitor Webhook Health**
   * Track failed deliveries in the CrissCross dashboard
   * Set up alerts for repeated failures

### Testing Webhooks

For development and testing:

1. Use the webhooks dashboard to view delivery history and inspect individual attempts
2. Test signature verification with sample payloads
3. Use the **Resend** action on any past message to redeliver it to your endpoint while iterating
4. If you don't have an endpoint ready yet, [Svix Play](https://play.svix.com) gives you a temporary public URL that captures incoming webhooks so you can inspect them in the browser

### Webhook Retries

If your endpoint returns a non-2xx response code or is unreachable, CrissCross automatically retries delivery on an exponential backoff schedule. Each delay is measured from the failure of the previous attempt:

| Attempt         | Delay after previous failure            |
| --------------- | --------------------------------------- |
| Initial attempt | Immediately when the event is generated |
| Retry 1         | 5 seconds                               |
| Retry 2         | 5 minutes                               |
| Retry 3         | 30 minutes                              |
| Retry 4         | 2 hours                                 |
| Retry 5         | 5 hours                                 |
| Retry 6         | 10 hours                                |
| Retry 7         | 10 hours                                |

After all retries are exhausted (roughly 28 hours after the initial attempt), the message is marked as `Failed` and no further automatic delivery attempts will be made. You can still recover it manually — see [Resending and Replaying Webhooks](#resending-and-replaying-webhooks).

A successful delivery at any point ends the retry sequence. A 2xx response from your endpoint is treated as success; anything else (including 3xx redirects and timeouts) counts as a failure.

### Delivery Failure Notifications

CrissCross emits two additional notifications you can subscribe to in order to monitor the health of your webhook integration:

| Event                       | When it fires                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------- |
| `message.attempt.exhausted` | A message exhausted all automatic retries and is now in the `Failed` state.           |
| `endpoint.disabled`         | An endpoint was automatically disabled after sustained delivery failures (see below). |

These are configured the same way as your other event subscriptions from the webhooks dashboard.

### Endpoint Auto-Disabling

If an endpoint experiences sustained delivery failures, CrissCross will automatically disable it to avoid sending traffic to a known-broken receiver. The criteria are:

* All delivery attempts to the endpoint have failed for at least **5 consecutive days**, **and**
* Multiple deliveries failed within a 24-hour span, with at least 12 hours between the first and last failure (this prevents brief outages from triggering disablement).

When this happens, an `endpoint.disabled` notification is sent. Re-enable the endpoint from the webhooks dashboard once the underlying issue is resolved. Use [recover or replay-missing](#resending-and-replaying-webhooks) to backfill any messages that were not delivered while the endpoint was disabled.

### Resending and Replaying Webhooks

CrissCross supports four manual recovery operations from the webhooks dashboard, covering anything from a one-off resend to backfilling an endpoint that was down for hours.

| Operation                   | Use it when                                                                                                                                                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Resend a single message** | You want to redeliver one specific event to one endpoint — for example, after fixing a bug in your handler.                                                                                                                         |
| **Replay missing messages** | An endpoint was down or misconfigured and you want to deliver only the messages that never succeeded since a given timestamp. Messages already delivered successfully are skipped.                                                  |
| **Recover failed messages** | You want to redeliver every message that ended in the `Failed` state since a given timestamp. Messages that eventually succeeded (even after retries) are not resent.                                                               |
| **Bulk replay**             | You want to redeliver **every** message — successful and failed — since a given timestamp. Useful when rebuilding downstream state from scratch. Be aware your endpoint will receive duplicates of events it has already processed. |

#### How to run a recovery

1. Open the webhooks dashboard and select the endpoint you want to recover.
2. For a single message, find the message in the delivery log and click **Resend**.
3. For the bulk operations, open the endpoint's actions menu, choose **Recover** or **Replay**, and pick the start timestamp. The dashboard will show progress and a count of messages re-queued.

Because these operations can deliver the same message more than once, handlers must be idempotent — see the [idempotency guidance](#best-practices) and deduplicate on the `svix-id` header.

> ℹ️ If you need to recover messages older than the retention window, contact your CrissCross account manager.

### IP Allowlisting

If your infrastructure requires IP allowlisting for incoming webhook traffic, contact your CrissCross account manager for the current list of source IP ranges. The list is updated periodically, so we recommend confirming it before any allowlist change is rolled out to production.

### Webhook Security Checklist

✅ Use HTTPS endpoints only\
✅ Verify webhook signatures\
✅ Store webhook secrets securely\
✅ Process events idempotently\
✅ Monitor failed deliveries\
✅ Implement proper error handling

> Real-time notifications