Webhooks

Receive real-time notifications when events occur in your ClawPay account.

Overview

Webhooks allow your application to receive HTTP POST requests when specific events happen. This is more efficient than polling the API and enables real-time integrations.

Creating Webhooks

Via API

const webhook = await client.webhooks.create({
  url: 'https://api.yourcompany.com/webhooks/clawpay',
  events: [
    'transaction.created',
    'transaction.completed',
    'authorization.required',
    'card.declined'
  ],
  secret: 'whsec_your_secret_key'
});

Via Dashboard

Navigate to Settings → Webhooks
Click "Add Endpoint"
Enter your URL and select events
Save and note your webhook secret

Event Types

Transaction Events

Event

Description

transaction.created

Transaction initiated

transaction.completed

Transaction successfully settled

transaction.failed

Transaction failed to process

transaction.refunded

Transaction refunded

Card Events

Event

Description

card.created

New card issued

card.activated

Card activated by cardholder

card.declined

Card transaction declined

card.frozen

Card frozen by user or system

card.cancelled

Card permanently cancelled

Authorization Events

Event

Description

authorization.required

Transaction requires manual approval

authorization.approved

Authorization request approved

authorization.denied

Authorization request denied

authorization.timeout

Authorization request timed out

Vault Events

Event

Description

vault.created

New vault created

vault.balance_low

Vault balance below threshold

vault.frozen

Vault frozen

vault.closed

Vault closed

Transfer Events

Event

Description

transfer.created

Transfer initiated

transfer.completed

Transfer completed

transfer.failed

Transfer failed

Webhook Payload

All webhooks follow this structure:

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "transaction.completed",
  "createdAt": "2024-01-15T14:22:35Z",
  "data": {
    "object": {
      "id": "txn_m3n4o5p6q7r8",
      "vaultId": "vault_1a2b3c4d5e6f",
      "cardId": "card_7g8h9i0j1k2l",
      "amount": 49.99,
      "currency": "USD",
      "status": "completed",
      "merchant": {
        "name": "Amazon Web Services",
        "category": "cloud_services"
      },
      "createdAt": "2024-01-15T14:22:33Z",
      "settledAt": "2024-01-15T14:22:35Z"
    }
  }
}

Verifying Signatures

Always verify webhook signatures to ensure requests are from ClawPay.

TypeScript/Node.js

import crypto from 'crypto';
import express from 'express';

const app = express();

app.post('/webhooks/clawpay',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-clawpay-signature'] as string;
    const payload = req.body.toString();

    const expectedSignature = crypto
      .createHmac('sha256', WEBHOOK_SECRET)
      .update(payload)
      .digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )) {
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(payload);

    // Process event
    switch (event.type) {
      case 'transaction.completed':
        handleTransactionCompleted(event.data.object);
        break;
      case 'card.declined':
        handleCardDeclined(event.data.object);
        break;
    }

    res.sendStatus(200);
  }
);

Using SDK

import { ClawPay } from '@clawpay/sdk';

app.post('/webhooks/clawpay', (req, res) => {
  const signature = req.headers['x-clawpay-signature'];

  try {
    const event = ClawPay.webhooks.verify(
      req.body,
      signature,
      WEBHOOK_SECRET
    );

    // Event is verified and parsed
    console.log(`Received ${event.type}`);

    res.sendStatus(200);
  } catch (err) {
    res.status(401).send('Invalid signature');
  }
});

Python

import hmac
import hashlib
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/clawpay', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Clawpay-Signature')
    payload = request.data

    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected_signature):
        return 'Invalid signature', 401

    event = request.json

    # Process event
    if event['type'] == 'transaction.completed':
        handle_transaction_completed(event['data']['object'])

    return '', 200

Go

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "io"
    "net/http"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    signature := r.Header.Get("X-Clawpay-Signature")

    body, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Cannot read body", http.StatusBadRequest)
        return
    }

    mac := hmac.New(sha256.New, []byte(WEBHOOK_SECRET))
    mac.Write(body)
    expectedSignature := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(signature), []byte(expectedSignature)) {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    var event WebhookEvent
    if err := json.Unmarshal(body, &event); err != nil {
        http.Error(w, "Invalid JSON", http.StatusBadRequest)
        return
    }

    // Process event
    switch event.Type {
    case "transaction.completed":
        handleTransactionCompleted(event.Data.Object)
    }

    w.WriteHeader(http.StatusOK)
}

Best Practices

1. Respond Quickly

Respond with 200 OK within 5 seconds. Process events asynchronously:

app.post('/webhooks/clawpay', async (req, res) => {
  const event = verifyWebhook(req);

  // Respond immediately
  res.sendStatus(200);

  // Process asynchronously
  processEventAsync(event).catch(err => {
    console.error('Failed to process event:', err);
  });
});

2. Handle Idempotency

Events may be delivered more than once. Use the event ID to track processed events:

const processedEvents = new Set();

async function handleWebhook(event) {
  if (processedEvents.has(event.id)) {
    console.log('Event already processed');
    return;
  }

  // Process event
  await processEvent(event);

  // Mark as processed
  processedEvents.add(event.id);
  await db.events.insert({ id: event.id, processedAt: new Date() });
}

3. Use HTTPS

Webhook URLs must use HTTPS in production. HTTP is only allowed in sandbox mode.

4. Monitor Webhook Health

Check webhook delivery status in your dashboard or via API:

const webhook = await client.webhooks.retrieve('webhook_123');
console.log(`Success rate: ${webhook.successRate}%`);
console.log(`Last delivery: ${webhook.lastDeliveryAt}`);

Retry Logic

If your endpoint returns a non-2xx status code, ClawPay will retry delivery:

Retry 1: 5 seconds later
Retry 2: 1 minute later
Retry 3: 10 minutes later
Retry 4: 1 hour later

After 4 failed attempts, the webhook is marked as failed and you'll receive an email notification.

Testing Webhooks

Test Events

Send test events to verify your endpoint:

await client.webhooks.sendTestEvent('webhook_123', {
  type: 'transaction.completed'
});

Local Development

Use tools like ngrok to expose your local server:

# Start ngrok
ngrok http 3000

# Use the ngrok URL in webhook configuration
https://abc123.ngrok.io/webhooks/clawpay

Webhook Inspector

View webhook delivery logs in the dashboard:

Request payload
Response status
Response body
Timestamp
Retry attempts

Example Integrations

Slack Notifications

async function handleCardDeclined(transaction) {
  await fetch(SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `🚨 Card declined`,
      blocks: [{
        type: 'section',
        text: {
          type: 'mrkdwn',
          text: [
            `*Card:* •••• ${transaction.card.last4}`,
            `*Amount:* $${transaction.amount}`,
            `*Merchant:* ${transaction.merchant.name}`,
            `*Reason:* ${transaction.declineReason}`
          ].join('\n')
        }
      }]
    })
  });
}

Database Sync

async function syncTransactionToDatabase(transaction) {
  await db.transactions.upsert({
    where: { id: transaction.id },
    update: {
      status: transaction.status,
      settledAt: transaction.settledAt
    },
    create: {
      id: transaction.id,
      vaultId: transaction.vaultId,
      amount: transaction.amount,
      currency: transaction.currency,
      merchantName: transaction.merchant.name,
      status: transaction.status,
      createdAt: transaction.createdAt
    }
  });
}

Email Alerts

async function sendAuthorizationRequest(authorization) {
  const approvers = authorization.policy.approvers;

  for (const approver of approvers) {
    await sendEmail({
      to: approver,
      subject: 'Transaction Approval Required',
      html: `
        <h2>Transaction Approval Request</h2>
        <p>A transaction requires your approval:</p>
        <ul>
          <li>Amount: $${authorization.amount}</li>
          <li>Merchant: ${authorization.merchant.name}</li>
          <li>Requested by: ${authorization.requestedBy}</li>
        </ul>
        <a href="https://app.useclawpay.app/approvals/${authorization.id}">
          Review Transaction
        </a>
      `
    });
  }
}

Webhook Security

IP Allowlist

Restrict webhook traffic to ClawPay IPs:

52.89.214.238
34.212.75.30
54.218.53.128

Updated list: docs.useclawpay.app/ips

Rate Limiting

ClawPay respects rate limits. If your endpoint returns 429 Too Many Requests, we'll back off and retry later.

Timeout

Webhook requests timeout after 10 seconds. Ensure your endpoint responds quickly.

Disabling Webhooks

Disable a webhook without deleting it:

await client.webhooks.update('webhook_123', {
  enabled: false
});

Webhook Limits

Plan

Max Webhooks

Max Retries

Retention

Free

7 days

Pro

30 days

Enterprise

Unlimited

Custom

Next Steps

PreviousVault Operations NextREST API

Last updated 1 hour ago

Good evening

hashtagOverview

hashtagCreating Webhooks

hashtagVia API

hashtagVia Dashboard

hashtagEvent Types

hashtagTransaction Events

hashtagCard Events

hashtagAuthorization Events

hashtagVault Events

hashtagTransfer Events

hashtagWebhook Payload

hashtagVerifying Signatures

hashtagTypeScript/Node.js

hashtagUsing SDK

hashtagPython

hashtagGo

hashtagBest Practices

hashtag1. Respond Quickly

hashtag2. Handle Idempotency

hashtag3. Use HTTPS

hashtag4. Monitor Webhook Health

hashtagRetry Logic

hashtagTesting Webhooks

hashtagTest Events

hashtagLocal Development

hashtagWebhook Inspector

hashtagExample Integrations

hashtagSlack Notifications

hashtagDatabase Sync

hashtagEmail Alerts

hashtagWebhook Security

hashtagIP Allowlist

hashtagRate Limiting

hashtagTimeout

hashtagDisabling Webhooks

hashtagWebhook Limits

hashtagNext Steps

Overview

Creating Webhooks

Via API

Via Dashboard

Event Types

Transaction Events

Card Events

Authorization Events

Vault Events

Transfer Events

Webhook Payload

Verifying Signatures

TypeScript/Node.js

Using SDK

Python

Go

Best Practices

1. Respond Quickly

2. Handle Idempotency

3. Use HTTPS

4. Monitor Webhook Health

Retry Logic

Testing Webhooks

Test Events

Local Development

Webhook Inspector

Example Integrations

Slack Notifications

Database Sync

Email Alerts

Webhook Security

IP Allowlist

Rate Limiting

Timeout

Disabling Webhooks

Webhook Limits

Next Steps