Build Your First Connector

This guide walks you through creating a webhook connector for Monetro.

Step 1: Define the Connector

Add your connector to backend/src/lib/connectorRegistry.ts:

{
  slug: 'my-provider',
  name: 'My Payment Provider',
  description: 'Import payments from My Provider.',
  category: 'zahlungen',
  icon: 'payment',
  version: '1.0.0',
  author: 'Your Company',
  requiredPlan: 'starter',
  hasWebhook: true,
  webhookPathTemplate: '/api/payment-import/my-provider/:token',
  webhookEvents: ['payment.completed'],
  docsUrl: 'https://docs.my-provider.com/webhooks',
  tags: ['payments', 'webhooks'],
  settingsSchema: [
    { key: 'apiKey', label: 'API Key', type: 'password', encrypted: true },
    { key: 'defaultSupplierId', label: 'Default Supplier', type: 'text' },
    { key: 'defaultCategoryId', label: 'Default Account', type: 'text' },
  ],
}

Step 2: Add the Webhook Handler

In paymentImportController.ts, add a handler:

export async function handleMyProviderWebhook(req: Request, res: Response) {
  const { token } = req.params
  const tenant = await resolveTenantByToken('my-provider', token)
  if (!tenant) return res.status(404).json({ error: 'Unknown token' })

  const event = JSON.parse(req.body.toString())

  const invoice: NormalizedInvoice = {
    provider: 'my-provider',
    externalId: event.id,
    supplierName: event.merchant_name,
    amount: event.amount / 100,
    taxRate: 20,
    currency: 'EUR',
    date: new Date(event.created_at),
    description: event.description,
  }

  await createIncomingInvoice(tenant, invoice)
  res.json({ received: true })
}

Step 3: Register the Route

In routes/paymentImport.ts:

router.post('/my-provider/:token', handleMyProviderWebhook)

Step 4: Test

1. Install the connector via the Connector Store UI
2. Configure the API key / webhook secret
3. Copy the webhook URL
4. Send a test webhook from your provider
5. Verify an incoming invoice was created

tip

Use webhook.site to inspect payloads during development.