Webhooks

Monetro receives webhooks from external payment providers to automatically create incoming invoices, match suppliers, and post transactions to the ledger.

Webhook URL Format

Each connector has a unique webhook URL scoped to your tenant:

https://app.monetro.at/api/payment-import/{provider}/{token}

• {provider} --- The payment provider slug (e.g., stripe, paypal)
• {token} --- A unique verification token generated when the connector is installed

tip

Find your webhook URL in Settings > Connectors after installing a payment connector. Copy it into your payment provider's webhook configuration.

Supported Providers

Provider	Events	Verification Method
Stripe	invoice.payment_succeeded, invoice.payment_failed, charge.refunded	Stripe-Signature header (HMAC-SHA256)
PayPal	PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED	CRC32-based HMAC verification
Mollie	payment.paid, payment.expired, refund.created	API key fetch verification
Revolut	payment_completed, payment_failed	Revolut-Signature header (HMAC-SHA256 + timestamp)

Processing Pipeline

When Monetro receives a webhook, it executes the following steps in order:

1. Signature Verification

The webhook handler verifies the request authenticity using the provider-specific method. Invalid signatures are rejected with 400 Bad Request.

2. Tenant Resolution

The token from the URL is validated against stored connector installations. If the token does not match any active installation, the webhook is rejected with 404 Not Found.

3. Supplier Resolution

Monetro attempts to find an existing supplier matching the payment provider:

• Matches by provider-specific merchant ID or email
• If no supplier exists, one is auto-created with the metadata from the webhook payload
• If a default supplier is configured in the connector settings, that supplier is used

4. Invoice Creation

An incoming invoice (eingangsrechnung) is created from the webhook data:

{
  "type": "eingangsrechnung",
  "supplierId": "supplier-uuid",
  "invoiceNumber": "pi_3abc123...",
  "invoiceDate": "2026-03-22",
  "totalGross": "99.00",
  "currency": "EUR",
  "source": "stripe",
  "externalId": "pi_3abc123def456"
}

5. Duplicate Detection

Before creating the invoice, Monetro checks for existing records with the same externalId and source. If a duplicate is found, the webhook is acknowledged with 200 OK but no new record is created. This ensures idempotent processing even if a provider sends the same event multiple times.

6. Auto-Post to Ledger

If the tenant has auto-posting enabled in their connector settings, the incoming invoice is automatically posted to the general ledger:

• Debit: Expense account (mapped in connector settings or auto-detected)
• Credit: Bank / payment provider clearing account

Security Considerations

caution

• Always use HTTPS --- Monetro rejects webhook requests over plain HTTP
• Webhook tokens are secrets --- Treat your webhook URL like a password. If compromised, uninstall and reinstall the connector to generate a new token
• IP allowlisting --- For additional security, restrict webhook sources to provider IP ranges in your firewall

Testing Webhooks

During development, use webhook.site to inspect webhook payloads before pointing them at Monetro.

To trigger a test webhook from within Monetro:

curl -X POST https://app.monetro.at/api/connectors/{slug}/test-webhook \
  -H "Authorization: Bearer <token>"

This sends a synthetic event through the full processing pipeline and returns the result without persisting any data.

Webhook Logs

Every received webhook is logged for debugging. Retrieve the webhook history for a connector:

curl "https://app.monetro.at/api/connectors/{slug}/webhook-logs?limit=20" \
  -H "Authorization: Bearer <token>"

Response (200 OK):

[
  {
    "id": "log-uuid",
    "provider": "stripe",
    "event": "invoice.payment_succeeded",
    "status": "processed",
    "externalId": "evt_3abc123",
    "receivedAt": "2026-03-22T14:30:00.000Z",
    "processedAt": "2026-03-22T14:30:01.200Z"
  }
]

Possible status values: processed, duplicate, failed, invalid_signature.