Webhooks

Real-time notifications for your InvoiceDoodle integration

Overview

Webhooks allow your application to receive real-time notifications about events that occur in your InvoiceDoodle account. Instead of polling our API, webhooks push data to your specified endpoint whenever an event occurs.

Security Best Practices

Always verify webhook signatures using your webhook secret
Use HTTPS endpoints for receiving webhooks
Implement proper error handling and retry logic
Store webhook secrets securely and never expose them in client-side code

Available Events

invoice.created

Triggered when a new invoice is created

{
  "event": "invoice.created",
  "data": {
    "invoice_id": "inv_123xyz",
    "amount": "1000.00",
    "currency": "USD",
    "status": "draft",
    "created_at": "2024-01-20T08:00:00Z"
  }
}

payment.received

Triggered when a payment is received (both crypto and traditional)

{
  "event": "payment.received",
  "data": {
    "payment_id": "pay_456abc",
    "invoice_id": "inv_123xyz",
    "amount": "1000.00",
    "currency": "USD",
    "payment_method": "crypto",
    "blockchain_tx": "0x1234...",
    "status": "confirmed",
    "received_at": "2024-01-20T08:05:00Z"
  }
}

smart_contract.executed

Triggered when a smart contract condition is met and executed

{
  "event": "smart_contract.executed",
  "data": {
    "contract_id": "con_789def",
    "invoice_id": "inv_123xyz",
    "condition": "payment_received",
    "action": "release_payment",
    "status": "completed",
    "executed_at": "2024-01-20T08:06:00Z"
  }
}

Implementation Examples

Register Webhook (cURL)

curl -X POST https://api.invoicedoodle.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhook",
    "events": ["invoice.created", "payment.received"],
    "secret": "your_webhook_secret"
  }'

Verify Webhook Signature (Node.js)

const crypto = require('crypto');

const verifyWebhookSignature = (payload, signature, secret) => {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
};

// Express route handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-invoicedoodle-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Handle webhook event
  const { event, data } = req.body;
  // Process the webhook data...

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

InvoiceDoodle