Webhooks

Receive real-time notifications when events occur in your MPPFi account. Webhooks enable your application to respond immediately to payments, policy violations, balance changes, and blockchain confirmations.

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 with AI agents.

Key Features:

• Real-time delivery: Events delivered within milliseconds

• Cryptographic signatures: HMAC-SHA256 verification for security

• Automatic retries: Exponential backoff for failed deliveries

• Blockchain confirmations: Events include on-chain transaction data

• Idempotent delivery: Duplicate events include same event ID

Creating Webhooks

Via API

const webhook = await mppfi.webhooks.create({
  url: 'https://api.yourcompany.com/webhooks/mppfi',
  events: [
    'payment.created',
    'payment.completed',
    'payment.failed',
    'policy.violation',
    'balance.low'
  ],
  description: 'Production webhook endpoint',
  secret: 'whsec_your_generated_secret_key'
});

console.log(`Webhook ID: ${webhook.id}`);
console.log(`Secret: ${webhook.secret}`); // Store securely

Via Dashboard

1. Navigate to Settings → Webhooks

2. Click "Add Endpoint"

3. Enter your URL and select events

4. Save and note your webhook secret

Event Types

Payment Events

Event	Description	Includes Blockchain Data
payment.created	Payment initiated	No
payment.processing	Payment submitted to blockchain	Yes
payment.completed	Payment confirmed on-chain	Yes
payment.failed	Payment failed to process	Yes (if tx submitted)
payment.refunded	Payment refunded	Yes

Agent Events

Event	Description
agent.created	New AI agent account created
agent.funded	Agent account received funds
agent.balance_low	Agent balance below threshold
agent.suspended	Agent account suspended

Policy Events

Event	Description
policy.created	New spending policy deployed
policy.updated	Policy rules modified
policy.violation	Payment blocked by policy
policy.approval_required	Multi-sig approval needed
policy.approval_granted	Approval signature received

Account Events

Event	Description
account.balance_updated	Account balance changed
account.balance_low	Balance below warning threshold
account.frozen	Account frozen by admin or policy
account.unfrozen	Account reactivated

Blockchain Events

Event	Description
blockchain.transaction_confirmed	On-chain tx reached finality
blockchain.block_missed	Transaction not included in expected block
blockchain.reorg_detected	Blockchain reorganization detected

Webhook Payload

All webhooks follow this structure:

{
  "id": "evt_9xK7mN4pQ2",
  "object": "event",
  "type": "payment.completed",
  "created_at": "2025-01-15T14:22:35Z",
  "data": {
    "object": {
      "id": "pmt_7xK9mN2pQ1",
      "agent_id": "agt_4zT8mN9pQ3",
      "amount": 50.00,
      "currency": "USDC",
      "status": "completed",
      "destination": {
        "address": "GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P"
      },
      "blockchain": {
        "network": "solana-mainnet",
        "signature": "5JzGW8jvKmF3X9vqYdN2pR7nL4cB8hZ1kQxE6tS3wP2mV9uA",
        "block": 245678901,
        "timestamp": "2025-01-15T14:22:35Z",
        "confirmations": 32
      },
      "created_at": "2025-01-15T14:22:33Z",
      "completed_at": "2025-01-15T14:22:35Z"
    }
  },
  "livemode": true
}

Verifying Signatures

CRITICAL: Always verify webhook signatures to ensure requests are from MPPFi.

TypeScript/Node.js

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

const app = express();

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

    // Verify timestamp to prevent replay attacks
    const currentTime = Math.floor(Date.now() / 1000);
    if (Math.abs(currentTime - parseInt(timestamp)) > 300) {
      return res.status(400).send('Timestamp too old');
    }

    // Construct signed payload
    const signedPayload = `${timestamp}.${payload}`;

    // Compute HMAC
    const expectedSignature = crypto
      .createHmac('sha256', WEBHOOK_SECRET)
      .update(signedPayload)
      .digest('hex');

    // Verify signature
    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 'payment.completed':
        handlePaymentCompleted(event.data.object);
        break;
      case 'policy.violation':
        handlePolicyViolation(event.data.object);
        break;
    }

    res.sendStatus(200);
  }
);

Using SDK

import { MPPFi } from '@mppfi/sdk';

const mppfi = new MPPFi({ apiKey: 'sk_live_...' });

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

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

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

    res.sendStatus(200);
  } catch (err) {
    console.error('Webhook verification failed:', err);
    res.status(401).send('Invalid signature');
  }
});

Python

import hmac
import hashlib
import time
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/mppfi', methods=['POST'])
def webhook():
    signature = request.headers.get('MPPFi-Signature')
    timestamp = request.headers.get('MPPFi-Timestamp')
    payload = request.data

    # Verify timestamp
    current_time = int(time.time())
    if abs(current_time - int(timestamp)) > 300:
        return 'Timestamp too old', 400

    # Construct signed payload
    signed_payload = f"{timestamp}.{payload.decode()}"

    # Compute HMAC
    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

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

    event = request.json

    # Process event
    if event['type'] == 'payment.completed':
        handle_payment_completed(event['data']['object'])
    elif event['type'] == 'policy.violation':
        handle_policy_violation(event['data']['object'])

    return '', 200

Rust

use actix_web::{web, App, HttpRequest, HttpResponse, HttpServer};
use hmac::{Hmac, Mac};
use sha2::Sha256;
use hex;

type HmacSha256 = Hmac<Sha256>;

async fn webhook_handler(
    req: HttpRequest,
    body: web::Bytes,
) -> HttpResponse {
    let signature = req.headers()
        .get("mppfi-signature")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");

    let timestamp = req.headers()
        .get("mppfi-timestamp")
        .and_then(|v| v.to_str().ok())
        .and_then(|s| s.parse::<i64>().ok())
        .unwrap_or(0);

    // Verify timestamp
    let current_time = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap()
        .as_secs() as i64;

    if (current_time - timestamp).abs() > 300 {
        return HttpResponse::BadRequest().body("Timestamp too old");
    }

    // Construct signed payload
    let payload = String::from_utf8_lossy(&body);
    let signed_payload = format!("{}.{}", timestamp, payload);

    // Compute HMAC
    let mut mac = HmacSha256::new_from_slice(WEBHOOK_SECRET.as_bytes())
        .expect("HMAC can take key of any size");
    mac.update(signed_payload.as_bytes());
    let expected_signature = hex::encode(mac.finalize().into_bytes());

    // Verify signature
    if signature != expected_signature {
        return HttpResponse::Unauthorized().body("Invalid signature");
    }

    // Parse event
    let event: serde_json::Value = serde_json::from_slice(&body)
        .expect("Failed to parse JSON");

    // Process event
    match event["type"].as_str() {
        Some("payment.completed") => {
            handle_payment_completed(&event["data"]["object"]);
        },
        Some("policy.violation") => {
            handle_policy_violation(&event["data"]["object"]);
        },
        _ => {}
    }

    HttpResponse::Ok().finish()
}

Event Examples

Payment Completed

{
  "id": "evt_9xK7mN4pQ2",
  "type": "payment.completed",
  "created_at": "2025-01-15T14:22:35Z",
  "data": {
    "object": {
      "id": "pmt_7xK9mN2pQ1",
      "agent_id": "agt_4zT8mN9pQ3",
      "amount": 50.00,
      "currency": "USDC",
      "status": "completed",
      "destination": {
        "address": "GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P",
        "name": "OpenAI API"
      },
      "blockchain": {
        "network": "solana-mainnet",
        "signature": "5JzGW8jvKmF3X9vqYdN2pR7nL4cB8hZ1kQxE6tS3wP2mV9uA",
        "block": 245678901,
        "timestamp": "2025-01-15T14:22:35Z",
        "confirmations": 32,
        "explorer_url": "https://solscan.io/tx/5JzGW8jvKmF3X9vqYdN2pR7nL4cB8hZ1kQxE6tS3wP2mV9uA"
      }
    }
  }
}

Policy Violation

{
  "id": "evt_3xL5mP9qR7",
  "type": "policy.violation",
  "created_at": "2025-01-15T15:30:00Z",
  "data": {
    "object": {
      "id": "pol_vio_5xK8mN3pQ2",
      "agent_id": "agt_4zT8mN9pQ3",
      "policy_id": "pol_7xK9mN2pQ1",
      "attempted_payment": {
        "amount": 600.00,
        "currency": "USDC",
        "destination": "GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P"
      },
      "violated_rules": [
        {
          "type": "amount_limit",
          "period": "daily",
          "limit": 500.00,
          "current": 450.00,
          "requested": 600.00,
          "message": "Daily spending limit of 500.00 USDC exceeded"
        }
      ],
      "action": "blocked",
      "timestamp": "2025-01-15T15:30:00Z"
    }
  }
}

Balance Low Warning

{
  "id": "evt_6xM2nP5qR9",
  "type": "account.balance_low",
  "created_at": "2025-01-15T16:00:00Z",
  "data": {
    "object": {
      "agent_id": "agt_4zT8mN9pQ3",
      "current_balance": 45.50,
      "currency": "USDC",
      "threshold": 100.00,
      "percentage_remaining": 45.5,
      "recommended_action": "fund_account"
    }
  }
}

Best Practices

1. Respond Quickly

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

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

  // Respond immediately
  res.sendStatus(200);

  // Process asynchronously (don't block response)
  processEventAsync(event).catch(err => {
    console.error('Failed to process event:', err);
    // Log to error tracking service
  });
});

2. Handle Idempotency

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

const processedEvents = new Set<string>();

async function handleWebhook(event: WebhookEvent) {
  // Check if already processed
  const exists = await db.events.findOne({ id: event.id });
  if (exists) {
    console.log(`Event ${event.id} already processed`);
    return;
  }

  // Process event
  await processEvent(event);

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

3. Use HTTPS

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

// Production webhook
url: 'https://api.yourcompany.com/webhooks/mppfi'  // ✅ Allowed

// Test mode only
url: 'http://localhost:3000/webhooks/mppfi'  // ⚠️ Test mode only

4. Monitor Webhook Health

Check webhook delivery status via dashboard or API:

const webhook = await mppfi.webhooks.retrieve('webhook_abc123');

console.log(`Success rate: ${webhook.success_rate}%`);
console.log(`Last delivery: ${webhook.last_delivery_at}`);
console.log(`Failed deliveries: ${webhook.failed_count}`);

// Get recent deliveries
const deliveries = await mppfi.webhooks.listDeliveries('webhook_abc123', {
  limit: 10
});

deliveries.forEach(d => {
  console.log(`${d.timestamp}: ${d.status} (${d.response_code})`);
});

5. Implement Retry Logic

If processing fails, implement your own retry mechanism:

import time
from redis import Redis

redis = Redis()

def process_webhook_with_retry(event, max_retries=3):
    retry_count = redis.get(f"webhook_retry:{event['id']}")
    retry_count = int(retry_count) if retry_count else 0

    if retry_count >= max_retries:
        # Max retries reached, log and alert
        log_failed_webhook(event)
        return

    try:
        process_event(event)
        # Success - clear retry counter
        redis.delete(f"webhook_retry:{event['id']}")
    except Exception as e:
        # Increment retry counter
        redis.incr(f"webhook_retry:{event['id']}")
        redis.expire(f"webhook_retry:{event['id']}", 3600)  # 1 hour TTL
        raise

Retry Logic

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

Attempt	Delay
1	Immediate
2	5 seconds
3	30 seconds
4	2 minutes
5	10 minutes
6	1 hour

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

Rate limiting: If your endpoint returns 429 Too Many Requests, MPPFi will respect the backoff and retry later.

Testing Webhooks

Send Test Events

// Send test event to webhook endpoint
await mppfi.webhooks.sendTestEvent('webhook_abc123', {
  type: 'payment.completed'
});

// Custom test payload
await mppfi.webhooks.sendTestEvent('webhook_abc123', {
  type: 'payment.completed',
  data: {
    object: {
      id: 'pmt_test_123',
      amount: 100.00,
      currency: 'USDC'
    }
  }
});

Local Development

Use tools like ngrok or LocalTunnel to expose your local server:

# Install ngrok
brew install ngrok

# Start your local server
npm start  # Runs on http://localhost:3000

# Expose via ngrok
ngrok http 3000

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

Webhook Inspector

View webhook delivery logs in the dashboard:

Dashboard → Webhooks → [Select Webhook] → Delivery Logs

Each delivery shows:

• Request payload (full JSON)

• Response status code

• Response body

• Response time

• Timestamp

• Retry attempts

Example Integrations

Slack Notifications

async function notifySlackOnPayment(payment: Payment) {
  await fetch(SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `Payment completed: ${payment.amount} ${payment.currency}`,
      blocks: [{
        type: 'section',
        text: {
          type: 'mrkdwn',
          text: [
            `*Payment ID:* ${payment.id}`,
            `*Amount:* ${payment.amount} ${payment.currency}`,
            `*Agent:* ${payment.agent_id}`,
            `*Destination:* ${payment.destination.address}`,
            `*Block:* ${payment.blockchain.block}`,
            `*Explorer:* ${payment.blockchain.explorer_url}`
          ].join('\n')
        }
      }]
    })
  });
}

Database Sync

async function syncPaymentToDatabase(payment: Payment) {
  await prisma.payment.upsert({
    where: { id: payment.id },
    update: {
      status: payment.status,
      blockchain_signature: payment.blockchain.signature,
      block_number: payment.blockchain.block,
      completed_at: payment.completed_at
    },
    create: {
      id: payment.id,
      agent_id: payment.agent_id,
      amount: payment.amount,
      currency: payment.currency,
      destination_address: payment.destination.address,
      status: payment.status,
      blockchain_signature: payment.blockchain.signature,
      block_number: payment.blockchain.block,
      created_at: payment.created_at,
      completed_at: payment.completed_at
    }
  });
}

Email Alerts

from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail

def send_policy_violation_alert(violation):
    message = Mail(
        from_email='[email protected]',
        to_emails='[email protected]',
        subject=f'Policy Violation: Agent {violation["agent_id"]}',
        html_content=f"""
        <h2>Spending Policy Violation Detected</h2>
        <p><strong>Agent:</strong> {violation['agent_id']}</p>
        <p><strong>Policy:</strong> {violation['policy_id']}</p>
        <p><strong>Attempted Amount:</strong> {violation['attempted_payment']['amount']} {violation['attempted_payment']['currency']}</p>
        <p><strong>Rules Violated:</strong></p>
        <ul>
            {''.join(f"<li>{rule['message']}</li>" for rule in violation['violated_rules'])}
        </ul>
        <p><strong>Action Taken:</strong> {violation['action']}</p>
        <p><a href="https://app.mppfi.xyz/agents/{violation['agent_id']}/activity">View Agent Activity</a></p>
        """
    )

    try:
        sg = SendGridAPIClient(SENDGRID_API_KEY)
        response = sg.send(message)
        print(f"Email sent: {response.status_code}")
    except Exception as e:
        print(f"Email failed: {e}")

Webhook Security

IP Allowlist

Restrict webhook traffic to MPPFi's IP addresses:

Production IPs:
- 52.89.214.238
- 34.212.75.30
- 54.218.53.128
- 3.101.94.52

Test Mode IPs:
- 54.241.31.99
- 54.241.31.102

Updated list: Check docs.mppfi.xyz/webhook-ips

Firewall configuration:

# Allow MPPFi webhook IPs
sudo ufw allow from 52.89.214.238 to any port 443
sudo ufw allow from 34.212.75.30 to any port 443
sudo ufw allow from 54.218.53.128 to any port 443
sudo ufw allow from 3.101.94.52 to any port 443

Rate Limiting

MPPFi respects rate limits. If your endpoint returns 429 Too Many Requests, deliveries will backoff and retry later.

// Example rate limiter middleware
import rateLimit from 'express-rate-limit';

const webhookLimiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minute
  max: 100, // 100 requests per minute
  message: 'Too many webhook requests'
});

app.post('/webhooks/mppfi', webhookLimiter, webhookHandler);

Timeout

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

Managing Webhooks

Update Webhook

await mppfi.webhooks.update('webhook_abc123', {
  events: [
    'payment.completed',
    'payment.failed',
    'policy.violation',
    'balance.low' // Added new event
  ]
});

Disable Webhook

Disable without deleting:

await mppfi.webhooks.update('webhook_abc123', {
  enabled: false
});

// Re-enable
await mppfi.webhooks.update('webhook_abc123', {
  enabled: true
});

Delete Webhook

client.webhooks.delete('webhook_abc123')

List Webhooks

let webhooks = client.webhooks().list(ListWebhooksParams {
    limit: Some(100),
    starting_after: None,
}).await?;

for webhook in webhooks {
    println!("Webhook: {}", webhook.id);
    println!("  URL: {}", webhook.url);
    println!("  Status: {}", if webhook.enabled { "enabled" } else { "disabled" });
    println!("  Success rate: {}%", webhook.success_rate);
}

Webhook Limits

Plan	Max Webhooks	Max Retries	Event Retention
Free	2	4	7 days
Pro	10	6	30 days
Enterprise	Unlimited	Custom	Custom

Troubleshooting

Webhook Not Receiving Events

1. Check webhook status: Verify it's enabled in dashboard

2. Verify URL: Ensure URL is publicly accessible via HTTPS

3. Check event subscriptions: Confirm events are selected

4. Review firewall rules: Allow MPPFi IP addresses

5. Test endpoint: Send test event via dashboard

Signature Verification Failing

1. Check secret key: Ensure using correct webhook secret

2. Verify timestamp: Check mppfi-timestamp header handling

3. Raw body: Use raw body (not parsed JSON) for verification

4. Timing attack protection: Use crypto.timingSafeEqual() or equivalent

High Failure Rate

1. Check response time: Endpoint must respond within 10 seconds

2. Return 200 OK: Even if async processing fails later

3. Handle errors: Log errors but still return 200

4. Review logs: Check webhook delivery logs in dashboard

Next Steps

• Configure Payments to trigger webhook events

• Set up Spending Policies for violation alerts

• Review API Reference for webhook endpoints

• Explore Architecture for system design