🧾Invoicing Events

Webhook events for Invoicing service.

Overview

Currently, the Invoicing service does not support webhooks in Docs-Dispatcher v1.0.

Invoicing Providers:

• iPaidThat

• Qonto

• PennyLane

• SuperPDP

None of these providers currently offer webhook integration through Docs-Dispatcher.

Why No Webhooks?

Invoicing operations are typically synchronous and complete quickly:

1. Fast Processing: Invoice generation completes in 2-5 seconds

2. Immediate Response: You get the invoice URL and ID immediately

3. No Long Delays: No need for async/webhook pattern

Typical workflow:

// Invoicing is synchronous - no webhook needed
const response = await fetch('/api/invoicing', {
  method: 'POST',
  body: JSON.stringify(request)
});

const { invoiceId, invoiceUrl } = await response.json();
console.log('Invoice created:', invoiceUrl); // Immediate result

Alternative: Polling Provider APIs

If you need to track invoice status changes (paid, overdue, etc.), poll the provider's API directly:

iPaidThat Status Polling

async function checkInvoiceStatus(invoiceId) {
  const response = await fetch(
    `https://api.ipaidthat.io/v1/invoices/${invoiceId}`,
    {
      headers: { 'Authorization': `Bearer ${ipaidThatApiKey}` }
    }
  );

  const invoice = await response.json();
  return invoice.status; // 'draft', 'sent', 'paid', 'overdue', 'canceled'
}

// Poll every 5 minutes
setInterval(async () => {
  const status = await checkInvoiceStatus('inv_123');
  if (status === 'paid') {
    await handleInvoicePaid('inv_123');
  }
}, 5 * 60 * 1000);

Qonto Webhook (Direct Integration)

Qonto offers native webhooks - integrate directly:

// Set up webhook in Qonto dashboard
app.post('/webhooks/qonto', (req, res) => {
  const { event, invoice } = req.body;

  if (event === 'invoice.paid') {
    console.log('Invoice paid:', invoice.id);
  }

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

Qonto Webhook URL: Configure in Qonto dashboard → Settings → Webhooks

Planned Future Support

Webhook support for Invoicing is planned for v2.0:

Planned Events:

• invoice.created - Invoice created successfully

• invoice.sent - Invoice sent to customer

• invoice.paid - Invoice marked as paid

• invoice.overdue - Payment deadline passed

• invoice.canceled - Invoice canceled

• invoice.credited - Credit note issued

Coming in v2.0 (Q4 2026): Webhooks for invoice lifecycle events will be available. Subscribe to the changelog for updates.

Current Workarounds

1. Use Sync Mode (Default)

# Wait for immediate response
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d @invoice-request.json

# Response includes invoice URL immediately
{
  "success": true,
  "invoiceId": "inv_abc123",
  "invoiceUrl": "https://qonto.com/invoices/abc123"
}

2. Provider Native Webhooks

Integrate directly with provider webhooks:

Provider	Native Webhooks	Setup
iPaidThat	❌ No	N/A
Qonto	✅ Yes	Qonto Dashboard → Webhooks
PennyLane	✅ Yes	PennyLane Dashboard → Webhooks
SuperPDP	❌ No	N/A

3. Database Polling

Store invoice IDs and poll for status:

// Store invoice after creation
await db.invoices.create({
  id: invoiceId,
  status: 'sent',
  providerUrl: invoiceUrl,
  createdAt: new Date()
});

// Background job polls for updates
async function syncInvoiceStatuses() {
  const pendingInvoices = await db.invoices.findMany({
    where: { status: { in: ['sent', 'overdue'] } }
  });

  for (const invoice of pendingInvoices) {
    const status = await fetchProviderStatus(invoice.id);
    if (status !== invoice.status) {
      await db.invoices.update({
        where: { id: invoice.id },
        data: { status }
      });
      await notifyStatusChange(invoice.id, status);
    }
  }
}

// Run every 15 minutes
setInterval(syncInvoiceStatuses, 15 * 60 * 1000);

Async Mode (Without Webhooks)

You can use async mode for invoicing, but no webhook is sent:

# Async mode queues request but doesn't send webhook
curl -X POST "https://api.docs-dispatcher.io/api/invoicing?async=true" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d @invoice-request.json

# Response
{
  "success": true,
  "dispatchId": "disp_xyz789",
  "status": "queued"
}

Note: You must poll for completion using dispatchId - no webhook notification is sent.

Comparison with Webhook Services

Feature	Invoicing	eSign	Postal
Webhook Support	❌ No	✅ Yes	✅ Yes
Async Required	❌ No	⚠️ Optional	⚠️ Optional
Response Time	2-5 sec	30-300 sec	60-600 sec
Best Mode	Sync	Async + Webhook	Async + Webhook

Next Steps

• Use Sync Mode - Default for invoicing

• Invoice Recipe - Complete workflow

• Provider Docs - Provider-specific details

• eSign Webhooks - Services that do support webhooks

• Webhook Fundamentals - How webhooks work

Getting Notified of Updates

Subscribe to updates for webhook support:

• Changelog: Version history

• GitHub: Watch releases (TBD)

• Email: Newsletter subscription (TBD)