HubSpot aan Moneybird koppelen: van gewonnen deal naar gecontroleerde factuur en betaalstatus

Je salescollega zet een deal in HubSpot op Gewonnen. Finance verwacht een juiste factuur in Moneybird, maar niemand wil later ontdekken dat de verkeerde bv, een oude prijs of 21 procent btw op de factuur staat. De betaalstatus moet daarna ook nog echt uit Moneybird komen, niet uit de dealstage.

De oplossing is geen rechtstreekse knop tussen twee systemen. Je bouwt een tussenlaag die de deal bevriest, gegevens matcht, een Moneybird-factuur als concept schrijft, het resultaat terugleest en pas na menselijke vrijgave verzendt. Betalingen, deelbetalingen en refunds volgen als eigen gebeurtenissen.

Een gecontroleerde HubSpot naar Moneybird-flow is een integratie waarin een gewonnen deal eerst een controleerbare factuurkandidaat wordt. De koppeling bewaart de bron en de gebruikte payload, voorkomt dubbele writes, leest de Moneybird-factuur terug en werkt de betaalstatus bij op basis van betalingen, niet op basis van CRM-stages.

Deze gids is voor een ondernemer, salesoperations-team of financeverantwoordelijke die HubSpot en Moneybird gebruikt en de hele buyer-flow wil beheersen. De productdetails, API-documentatie en prijzen zijn gecontroleerd op 20 oktober 2026. In de CRM-route die een gewonnen deal eerst als gecontroleerd Exact Online-concept behandelt blijft de betaalstatus eveneens een aparte werkelijkheid.

Eerst de koppelroute kiezen

Een HubSpot naar Moneybird-koppeling kan op drie manieren. De keuze hangt minder af van het aantal apps in een marktplaats dan van de variatie in je facturen en de kosten van een fout.

• Kant-en-klare connector: geschikt voor één administratie, één vast factuurmoment, stabiele klantrecords en weinig uitzonderingen. Controleer expliciet of de connector gekoppelde bedrijven, contactpersonen en line items gebruikt, een conceptfactuur schrijft, de Moneybird-ID terugleest en betalingen los van de dealstage synchroniseert.
• n8n of Make: geschikt wanneer je de flow zelf kunt beheren en de regels overzichtelijk blijven. Gebruik het platform voor orkestratie en meldingen, maar bewaar de snapshot, payloadhash, statussen en vrijgave in een eigen staginglaag.
• Eigen API-koppeling: passend bij meerdere administraties, meerdere factuurmomenten, afwijkende btw-regels, deelbetalingen, refunds of hoge foutkosten. Dan bouw je de factuurpoort rond jouw proces en niet rond de velden die een connector toevallig aanbiedt.

Mijn korte regel: een eenvoudige deal met één administratie kan met een connector. Zodra Gewonnen nog niet hetzelfde betekent als factureerbaar, moet de financiële beslissing buiten de connector liggen.

Wat je nodig hebt

Een integratie-engineer kan de API aanroepen. Die persoon kan geen onduidelijk factuurmoment of ontbrekende relatiekaart oplossen. Leg daarom eerst het contract tussen sales en finance vast.

• Een expliciete factureervoorwaarde. Gebruik de interne HubSpot-dealstage-ID voor Gewonnen als startsein, maar voeg een aparte eigenschap toe zoals factuurtoestemming, factuurmoment of oplevering goedgekeurd. Een gewonnen deal kan nog wachten op een aanbetaling, ondertekende oplevering of volgende termijn.
• Een bron voor de regels. Gebruik gekoppelde HubSpot line items, een goedgekeurde quote of een prijsdocument. Het bedrag op de deal is een controletotaal, geen factuurregelset.
• Relatiegegevens met vaste sleutels. Bewaar in HubSpot de Moneybird-contact-ID of een eigen externe klantcode. Een bedrijfsnaam, e-maildomein of vrij tekstveld is zoekhulp, geen definitieve sleutel.
• Een Moneybird-administratiekaart. Noteer de administratie-ID, contact-ID, omzetrekeningen, btw-tarieven, taal, valuta en betaaltermijn. Een verkoopfactuur gebruikt onder meer contact, referentie, factuurdatum, vervaldatum, valuta en regels met prijs, hoeveelheid, btw-tarief en grootboekrekening.
• Een staginglaag. Een tabel in PostgreSQL of Supabase is genoeg. Bewaar bron-snapshot, payload, hash, case-sleutel, versie, eigenaar, status, Moneybird-ID, foutcode en volgende actie.
• Een webhook-endpoint. Dit endpoint moet publiek via HTTPS bereikbaar zijn, de ruwe request body kunnen bewaren en snel antwoorden. De geldige betaling komt vaak lang nadat de factuur is gemaakt.
• Een testadministratie en proefset. Test een Nederlandse klant, twee btw-tarieven, ontbrekende contact-ID, dubbele webhook, time-out na een write, deelbetaling, betalingsterugdraaiing en refund.
• Een bevoegde vrijgever. Spreek af wie de voorgestelde factuur mag vrijgeven, binnen welke termijn en met welke reden bij weigering.
• Een budgetorde. Reken voor 20 oktober 2026 bij een kant-en-klare connector op ongeveer €25 tot €200 per maand voor Moneybird plus connector. Voor Make of n8n is €25 tot €350 per maand een bruikbare bandbreedte voor platform, Moneybird en eventuele hosting. Voor maatwerk reserveer je ongeveer €4.000 tot €12.000 eenmalig voor een eerste versie, daarna €150 tot €600 per maand voor hosting, monitoring en onderhoud. Plan bovendien jaarlijks 10 tot 20 procent van de bouwsom voor doorontwikkeling. Dit zijn planningsbandbreedtes, geen offerte: de actuele referenties verderop zijn Moneybird €3 tot €41 per maand bij jaarbetaling en n8n Cloud €20 tot €50 per maand; Make factureert per actie met credits.

HubSpot gebruikt bij deals interne waarden voor dealstage en pipeline. Een deal kan aan bestaande records worden gekoppeld via de associations-structuur. De actuele Deals API-documentatie beschrijft deze dealvelden en associaties, gecontroleerd op 20 oktober 2026.

Concrete stappen: van deal naar Moneybird en terug

Een controleerbare factuurflow zet een gewonnen HubSpot-deal om in een versieerbaar voorstel, matcht klant en regels, valideert btw, schrijft alleen een Moneybird-concept, leest dat terug en laat Finance vrijgeven. Daarna volgt de betaalstatus uit geregistreerde gebeurtenissen, niet uit de dealstage. Doorloop deze genummerde stappen in deze volgorde:

1. Trigger op factuurtoestemming, niet op de naam Gewonnen

Gebruik de dealstage als ingang, maar laat de stage niet zelfstandig een financiële write starten. Maak in HubSpot eigenschappen aan voor factuurtoestemming, factuurmoment, factuurstatus, Moneybird-factuur-ID, betaalstatus, openstaand bedrag en integratiesleutel.

De trigger kan een HubSpot-workflow, webhook of geplande controle zijn. Een webhook is snel, maar een geplande controle is een nuttige herstelroute voor gemiste events. Zet de kandidaat alleen door wanneer de aparte factuurvoorwaarde waar is. Bij een project kan dat een geaccepteerde oplevering zijn. Bij een abonnement kan dat de eerste factuurperiode zijn.

Bij HubSpot moet je twee routes voor inkomende requests uit elkaar houden. App-webhooks voor subscriptions van een app gebruiken de v3-signature: controleer X-HubSpot-Signature-v3 en X-HubSpot-Request-Timestamp, bereken HMAC-SHA-256 over methode, URI, ongewijzigde body en timestamp met het client secret en weiger een timestamp ouder dan vijf minuten. De HubSpot-validatiedocumentatie voor app-webhooks beschrijft deze v3-route, geraadpleegd op 20 oktober 2026.

De Workflow-actie Send a webhook is een ander pad. Kies onder Authentication type voor Include request signature in header en vul de App ID in. HubSpot stuurt dan X-HubSpot-Signature: een SHA-256-hash van de concatenatie van app-secret, HTTP method, URI en de ongewijzigde request body. Bereken precies die concatenatie; pas hier niet de v3-formule toe. De workflowdocumentatie beschrijft deze signature-instelling en verificatie, bijgewerkt op 16 september 2026.

Ook het retrypad verschilt. App-webhooks kunnen bij fouten maximaal tien keer opnieuw worden aangeboden, onder meer na een verbindingfout, timeout langer dan vijf seconden of een 4xx- of 5xx-respons. De Workflow-actie kan mislukte requests tot drie dagen opnieuw proberen, met maximaal acht uur tussen pogingen; 4xx wordt niet opnieuw geprobeerd, behalve 429. Behandel beide routes daarom als mogelijke duplicaten. De HubSpot-webhookdocumentatie beschrijft het retryvenster voor app-webhooks, gecontroleerd op 20 oktober 2026.

Controlepunt: je kunt voor elke kandidaat aanwijzen waarom deze deal nu factureerbaar is, los van de tekst Gewonnen.

2. Bevries de bron en maak één factuurcase

Lees de deal opnieuw uit voordat je iets naar Moneybird stuurt. Bewaar minimaal de HubSpot-deal-ID, pipeline, interne stage-ID, dealnaam, sluitdatum, valuta, factuurvoorwaarde, contractreferentie en snapshot-tijd. Lees ook de gekoppelde bedrijfs-, contact- en line-item-ID's opnieuw uit.

Bewaar per regel de bronwaarde en de genormaliseerde waarde. Zo zie je later of een Moneybird-regel uit een HubSpot-product, een quote of een handmatige correctie kwam. Een wijziging in HubSpot na de snapshot is een nieuwe payloadversie. Schrijf niet stilletjes over de oude kandidaat heen.

Gebruik een zakelijke case-sleutel, bijvoorbeeld:

case_key = hubspot:{deal_id}:{factuurmoment}:{moneybird_administration_id}
version_key = {case_key}:v{payload_version}

De case-sleutel houdt één zakelijke factuur bij. De versiesleutel houdt wijzigingen bij. Daarmee kan een retry dezelfde case hervatten, terwijl een gewijzigde prijs zichtbaar een nieuwe versie maakt.

Sla vóór elke externe write op: case-sleutel, versiesleutel, payloadhash, snapshot-tijd, status, Moneybird-contact-ID, Moneybird-factuur-ID, eigenaar, vervaltijd en laatste fout. Gebruik statussen zoals candidate, matched, validated, staged, written draft, readback ok, awaiting release, sent, payment open, partially paid, paid, refund pending, refunded en exception.

Controlepunt: een reviewer kan de voorgestelde factuur terugbrengen naar één dealversie, één regelset, één relatiekaart en één factuurmoment.

3. Match bedrijf, contact en factuuradres

Match eerst op een vaste sleutel. In Moneybird kan een externe klantcode op het contact worden bewaard. Een eigen veld zoals HubSpot-company-ID of customer-ID maakt later terugzoeken betrouwbaar. Als die sleutel ontbreekt, gebruik je btw-identificatienummer en juridische naam samen als kandidaat, nooit als stille automatische keuze.

Controleer deze volgorde:

1. HubSpot-bedrijf naar precies één Moneybird-contact.
2. HubSpot-contact naar de persoon die de factuur ontvangt, als dat in jouw proces relevant is.
3. Factuuradres en land tegen de Moneybird-contactgegevens.
4. Valuta en betaalconditie tegen het factuurbeleid.
5. Een geblokkeerde of gearchiveerde relatie naar een expliciete finance-beslissing.

Bij nul matches gaat de kandidaat naar contact not found. Bij twee matches naar contact ambiguous, met beide kandidaten in de queue. Laat een mens één keuze maken en schrijf die keuze terug naar de relatiekaart. De volgende deal hoeft dan niet opnieuw op naam te zoeken.

Maak een nieuwe Moneybird-contactpersoon alleen wanneer je beleid dat toestaat. Anders kan één tikfout in een e-mailadres tientallen dubbele contacten opleveren. Moneybird kan een extern contact-ID op een contact bewaren en later als zoekroute gebruiken.

Controlepunt: bedrijf, contact, adres en betalingsconditie zijn herleidbaar tot vaste IDs en er is geen vrije-tekstkeuze meer over.

4. Bouw de regels en beslis btw deterministisch

Lees per line item de omschrijving, hoeveelheid, eenheid, prijs, korting, valuta, lever- of prestatiedatum en btw-behandeling. Reken de netto som zelf opnieuw uit. Vergelijk die met het bedrag op de deal, maar gebruik dat bedrag niet als vervanging voor de regels. Bij verschil gaat de kandidaat naar amount mismatch.

Leg btw vast met een beslismatrix. Neem minimaal klantland, btw-identificatienummer, type dienst of product, plaats van prestatie, factuurmoment, verleggingsgrond en gekozen Moneybird-tax-rate-ID mee. Een nieuwe combinatie gaat naar finance. Laat een taalmodel hooguit uitleg of een ontbrekend veld signaleren. Laat het geen btw-tarief kiezen.

De Belastingdienst noemt onder meer naam en adres van beide partijen, factuurdatum, uniek opeenvolgend factuurnummer, omschrijving, leverdatum, bedrag exclusief btw, btw-tarief en btw-bedrag als factuurgegevens. De actuele factuureisen van de Belastingdienst geven de volledige lijst, gecontroleerd op 20 oktober 2026.

Een Moneybird-regel heeft meer nodig dan tekst en bedrag. Bewaar per regel het gekozen btw-tarief en de omzetrekening. Verzendkosten, korting, voorschot en meerwerk horen als eigen regels of expliciete correcties in de payload te staan.

Controlepunt: netto, btw en totaal zijn opnieuw berekend. Elke regel heeft een bron, tax-rate-ID, omzetrekening, hoeveelheid en prijs.

5. Maak de write idempotent en beperk de rechten

Zet een unieke databaseconstraint op de case-sleutel. Zet een tweede constraint op de Moneybird-factuur-ID zodra die waarde bekend is. Gebruik een lock op de case voordat je de bestaande status leest of een externe write begint. Een dubbele webhook wacht dan op de eerste poging en leest daarna dezelfde uitkomst terug.

Het gedrag na een retry is strikt:

• Zelfde payloadhash, Moneybird-ID bekend: doe geen nieuwe POST. Lees de bestaande factuur terug.
• Zelfde payloadhash, geen Moneybird-ID: controleer staging, log en Moneybird op een eerder aangemaakte factuur voordat je opnieuw schrijft. Een timeout zegt niet of de externe write is mislukt.
• Nieuwe payloadhash vóór de write: maak versie 2 onder dezelfde case en laat versie 1 zichtbaar vervallen.
• Nieuwe payloadhash na een bestaande Moneybird-factuur: blokkeer automatisch. Laat finance beslissen of de bestaande factuur wordt aangepast, gecrediteerd of vervangen.

Geef de Moneybird-token alleen de scopes die deze administratie en actie nodig hebben. Een flow die een conceptfactuur mag maken, hoeft geen brede beheerrechten te krijgen. Sla tokens en webhooksecrets op in een secret manager en log nooit de volledige token of handtekening.

OWASP adviseert voor geautomatiseerde systemen least privilege, server-side validatie, expliciete menselijke goedkeuring bij risicovolle acties en replay-bescherming. De OWASP-richtlijn zet deze maatregelen naast elkaar, geraadpleegd op 20 oktober 2026.

Controlepunt: dezelfde event-aanbieding levert dezelfde case en hooguit één Moneybird-factuur op.

6. Schrijf een Moneybird-concept en lees het terug

Maak eerst of vind het Moneybird-contact. Gebruik daarna de verkoopfactuur-write met de gematchte contact-ID, referentie naar de HubSpot-deal, factuurdatum, vervaldatum, valuta en regels. Per regel horen omschrijving, prijs, hoeveelheid, tax-rate-ID en ledger-account-ID.

De actuele Moneybird-handleiding voor verkoopfacturen laat deze volgorde zien: contact vinden of maken, verkoopfactuur met regels maken en pas daarna verzenden. Versturen verandert een factuur van draft naar open; dat is precies waarom de eerste write nog geen bericht naar de klant moet sturen. De officiële handleiding vermeldt deze velden en de overgang van draft naar open, laatst gewijzigd op 19 oktober 2026.

Sla de response op en lees de factuur daarna opnieuw met de ontvangen Moneybird-ID. Vergelijk minimaal:

• Moneybird-contact, referentie, valuta en factuurdatum.
• Alle regels, hoeveelheden, prijzen, btw-tarieven en omzetrekeningen.
• Netto, btw, totaal en vervaldatum.
• De koppeling naar case-sleutel, HubSpot-deal en payloadversie.

Een succesvolle HTTP-response is geen inhoudelijke controle. De read-back is het bewijs dat de juiste data in het financiële systeem staat. Bij verschil gaat de factuur naar readback mismatch; de flow verzendt niets.

Controlepunt: de stagingrecord bevat de Moneybird-ID, de exacte response en een read-back die gelijk is aan de goedgekeurde payload.

7. Laat Finance de exacte factuur vrijgeven

Toon de vrijgever de bron-snapshot, de relatiekeuze, de btw-beslissing, de Moneybird-response en de read-back naast elkaar. Laat de knop verwijzen naar één payloadversie, niet naar een deal die intussen kan zijn gewijzigd.

Leg vast: vrijgegeven door, vrijgegeven op, reden, payloadhash, Moneybird-ID en vervolgactie. Bij weigeren gaat de case naar rejected met een concrete code, zoals terms changed, vat unknown of readback mismatch. Bij verlopen goedkeuring controleert de flow kritieke HubSpot-velden opnieuw.

Verzenden is een aparte actie. Een conceptfactuur kan bewust intern blijven totdat de klantgegevens en regels zijn gecontroleerd. Na vrijgave roept de flow pas de Moneybird-actie aan die de factuur naar de klant stuurt. Update HubSpot pas naar invoice status sent wanneer Moneybird die toestand aantoonbaar teruggeeft.

Controlepunt: iedere verzonden factuur heeft één snapshot, één stagingpayload, één Moneybird-ID, één read-back en één menselijke beslissing.

8. Volg betalingen met signature, event en read-back

Maak in Moneybird een webhook voor de betaalstatus en bewaar het secret in een secret manager. De API geeft het secret één keer terug in de response op het aanmaken van de webhook; GET-, activate- en deactivate-responses bevatten het niet. Je kunt het later op de webhookdetailpagina na MFA onthullen en daar ook roteren. Kies bij rotatie een grace period waarin het oude secret naast het nieuwe geldig blijft; tijdens die periode bevat de header een v1-digest per actief secret en accepteer je iedere overeenkomende digest. Moneybird documenteert het onthullen, roteren en uitfaseren van het webhook-secret, laatst gewijzigd op 19 oktober 2026. De webhook bevat onder meer een Moneybird-Signature en een unieke Idempotency-Key.

De huidige signature is opgebouwd uit een timestamp en een of meer v1-waarden. Bereken HMAC-SHA256 over timestamp plus een punt plus de ruwe request body, vergelijk constant-time en accepteer geen timestamp die meer dan vijf minuten afwijkt. Gebruik de ongewijzigde bytes van de body. Eerst JSON parsen en daarna opnieuw serialiseren kan de signature ongeldig maken.

Moneybird verwacht HTTP 200 snel. Bij een andere status probeert het systeem een push tien keer opnieuw met oplopende tussenpozen. Sla het event op, controleer de signature, zet de event-idempotentiesleutel vast en geef daarna 200 terug. Verwerk de betaling asynchroon. De actuele webhookdocumentatie beschrijft retries en Idempotency-Key, laatst gewijzigd op 19 oktober 2026.

Abonneer je voor deze buyer-flow minimaal op:

• sales invoice state changed to paid voor een volledig betaalde verkoopfactuur.
• payment registered om deelbetalingen te zien.
• payment destroyed om een teruggedraaide of verwijderde betaling te verwerken.
• Eventueel sales invoice state changed om open, laat en betaalde toestanden in één stream te ontvangen.

De betaalhandleiding van Moneybird noemt de betaaldevents voor volledige betaling en de twee payment-events voor deelbetalingen of reversals. De aanbevolen events en de read-backstap staan in de officiële betaalhandleiding, laatst gewijzigd op 19 oktober 2026.

Gebruik het event niet als volledige waarheid. Haal na ontvangst de actuele verkoopfactuur op. In de payload kan state de toestand zijn die het event veroorzaakte, terwijl entity intussen al een nieuwere toestand bevat. Werk HubSpot bij met betaalstatus, betaald bedrag, openstaand bedrag, laatste betaaldatum en eventueel de Moneybird-payment-ID.

De aparte Moneybird Payments API geeft per betaling onder meer invoice-ID, prijs, betaaldatum, financial-mutation-ID en een eventuele credit-invoice-ID. De actuele Payments API documenteert deze velden voor een terugleesbare betaling, gecontroleerd op 20 oktober 2026.

De sales-invoices API levert naast state ook payments, total_paid, total_unpaid en original_sales_invoice_id terug. Voor een creditfactuur verlangt Moneybird een oorspronkelijke factuur en moeten beide documenten een betaalbare toestand hebben. De actuele sales-invoices API beschrijft deze betaal- en creditfactuurvelden, gecontroleerd op 20 oktober 2026.

Gebruik aparte velden voor betaalstatus, creditstatus, reversalstatus en refundstatus:

• Betaling geregistreerd: voeg alleen een geldig Moneybird-paymentrecord toe aan het betaalde bedrag en bewaar payment-ID, bedrag en datum. Dit is bewijs van een geregistreerde betaling, nog niet automatisch van volledige betaling.
• Gedeeltelijk betaald: de som van niet-teruggedraaide geregistreerde betalingen is lager dan het factuurtotaal en hoger dan nul; zet CRM op gedeeltelijk betaald.
• Betaald: zet CRM pas op betaald wanneer de actuele Moneybird-state betaald is, total_unpaid nul is en geldige geregistreerde betalingsallocaties het factuurtotaal dekken. Een nulbedrag door alleen een creditfactuur, verrekening, afboeking of correctie is geen betaalbewijs.
• Creditfactuur of verrekening: bewaar het creditbedrag en de verwijzing naar de oorspronkelijke factuur; zet CRM op gecrediteerd of verrekend, niet op betaald. De oorspronkelijke factuur blijft een eigen document.
• Betaling teruggedraaid: verwerk payment destroyed of een bevestigde reversal, trek het bedrag af van de geldige betaalallocaties en zet CRM op betaling teruggedraaid, open of gedeeltelijk betaald.
• Refund: registreer een echte terugbetaling als eigen refundcase met bedrag, datum en bewijs; zet CRM eerst op refund in behandeling en daarna op terugbetaald. Laat betaald en terugbetaald als afzonderlijke statussen bestaan.

Een factuurstatus en financiële statussen zijn dus verschillende kolommen. Sent zegt dat een factuur is verzonden. Betaald zegt dat geld is geregistreerd en de betaalvoorwaarden hierboven zijn vervuld. Gecrediteerd, verrekend, teruggedraaid en terugbetaald beschrijven andere gebeurtenissen. De dealstage zegt alleen waar sales de commerciële kans heeft gezet.

9. Behandel refunds als een eigen case

Een refund is geen gewone statusupdate van de deal. Maak een refundcase met verwijzing naar de oorspronkelijke HubSpot-deal, de oorspronkelijke Moneybird-factuur, het terug te betalen bedrag, de betrokken regels, reden, datum en bewijs. Bij een gedeeltelijke refund wijs je het bedrag toe aan concrete regels.

De veilige route is: refund ontvangen, bedrag en originele factuur matchen, creditfactuur of correctie voorbereiden, read-back controleren en pas daarna vrijgeven. Laat een refund niet opnieuw de oorspronkelijke factuur overschrijven. Houd de originele factuur, de creditfactuur en de bijbehorende betaling afzonderlijk traceerbaar.

Moneybird heeft in zijn eventlijst aparte signalen voor een creditfactuur die uit een origineel document is gemaakt en voor wijzigingen in factuur- en betaaltoestanden. De actuele eventlijst toont deze afzonderlijke credit- en payment-events, geraadpleegd op 20 oktober 2026.

Controlepunt: een refund kan worden gereconstrueerd zonder de oorspronkelijke factuur of de betaalhistorie te overschrijven.

Valkuilen die pas bij een fout zichtbaar worden

De happy path is kort. De uitzonderingen bepalen of je cijfers betrouwbaar blijven.

• Gewonnen wordt als factuur gebruikt. Maak een aparte factuurvoorwaarde. Zonder contract-, oplever- of termijnbewijs blijft de case in billing gate missing.
• Het dealbedrag vervangt de regels. Herlees de line items en vergelijk de som met het bedrag. Bij verschil geen write.
• Een bedrijfsnaam kiest de verkeerde klant. Match op Moneybird-contact-ID of externe klantcode. Twee kandidaten gaan naar contact ambiguous.
• Btw wordt gegokt. Gebruik een vaste matrix en stuur onbekende combinaties naar finance.
• De webhook wordt vertrouwd zonder signature. Valideer de ruwe body, timestamp en HMAC vóór je een event opslaat of uitvoert.
• Een 200-respons betekent dat de verwerking klaar is. Geef snel 200 na signature- en eventregistratie. Laat de financiële verwerking in een queue lopen.
• Een time-out maakt een tweede factuur. Zoek eerst op case-sleutel, payloadhash en bestaande Moneybird-ID. Een onbekende externe uitkomst is een reconciliatiegeval.
• De eventstatus is verouderd. Lees de actuele factuur terug. De eventpayload en de huidige entity kunnen verschillen.
• Deelbetaling wordt als betaald gemarkeerd. Bereken betaald en openstaand bedrag. Een betaling van €1.000 op een factuur van €2.500 is geen betaald.
• Een refund verandert alleen CRM. Maak een credit- of refundcase en koppel die aan de originele factuur.
• De vrijgever keurt een veranderlijke deal goed. Laat een goedkeuring verlopen en controleer de payloadhash opnieuw.
• De uitzonderingsqueue zegt alleen controleer. Gebruik vaste codes, eigenaar, deadline, bewijs en volgende actie.

Een queue is pas nuttig als hij beslissingen versnelt. Meet daarom hoeveel cases op ontbrekende contacten, onbekende btw, read-backverschillen, dubbele kandidaten, teruggedraaide betalingen en openstaande refunds eindigen. Als één code steeds terugkomt, verbeter je de bron of het proces. Je voegt niet eindeloos meer handmatige controle toe.

Beslis-kader: connector, Make, n8n of maatwerk

Leg vier vragen naast elkaar: hoe stabiel zijn klant en regels, hoeveel uitzonderingen komen voor, hoe hoog is de foutschade en wie beheert de flow?

Kant-en-klaar past wanneer je één Moneybird-administratie hebt, vrijwel altijd hetzelfde factureert en geen menselijke vrijgave buiten de bestaande boekhoudflow nodig hebt. Vraag de leverancier om een antwoord op vijf punten: line items, btw per regel, conceptstatus, veilige retry en betaalstatus. Een connector die alleen contact en totaal doorstuurt, is voor deze buyer-flow te klein.

Make rekent met credits per moduleactie. Een webhook ontvangen, record zoeken, record maken en record bijwerken verbruiken dus ieder hun eigen credits. De officiële prijspagina vermeldt dat een scenario per actie credits verbruikt en dat inkomende webhooks worden opgehouden wanneer credits op zijn. De actuele Make-documentatie beschrijft credits en de webhookqueue, gecontroleerd op 20 oktober 2026. Make is bruikbaar voor zichtbare orkestratie, maar de auditlaag hoort niet uitsluitend in de scenariohistorie te staan.

n8n Cloud rekent per volledige workflow-uitvoering, ongeacht het aantal stappen. Op 20 oktober 2026 kost Starter €20 per maand bij jaarlijkse betaling voor 2.500 uitvoeringen en Pro €50 voor 10.000 uitvoeringen. n8n noemt ook onbeperkte stappen per uitvoering. De actuele prijspagina van n8n vermeldt deze plannen en rekeneenheid, gecontroleerd op 20 oktober 2026. n8n past goed wanneer je eigen HTTP-calls, code en uitzonderingspaden nodig hebt, zolang staging en rechten buiten de workflow goed zijn geregeld.

Maatwerk past zodra deelbetalingen, refunds, meerdere administraties, verschillende factureermomenten of hoge foutkosten de normale situatie zijn. Bouw dan eerst de release- en statuslaag. De HubSpot-trigger, Moneybird-adapter en webhookverwerking kunnen daar omheen wisselen.

Automatiseer nog niet als er geen vaste bron voor de factuurregels is, Moneybird-contacten niet uniek zijn of niemand bevoegd is om uitzonderingen vrij te geven. Eerst de relatiekaart en het factuurbeleid op orde brengen is dan de snelste route.

De keuzehulp zegt hetzelfde als het geschreven kader. Stabiele regels en weinig foutkosten passen bij een connector. Meer uitzonderingen passen bij Make of n8n met een eigen staginglaag. Zodra de factuur een financieel besluit wordt, hoort een release-service de grens te bewaken.

Uitgewerkt voorbeeld: Noordlicht Installaties BV

Dit is een synthetisch voorbeeld met voorbeeld-ID's. De bedragen laten zien hoe de controle werkt.

Noordlicht Installaties BV wint in HubSpot deal HS-1042. De afspraak is dat de eerste factuur na ondertekende oplevering mag worden gemaakt. Op 17 oktober 2026 vult de projectleider factuurtoestemming=true en opleverdocument ACC-2026-1017 in. De dealwaarde is €7.500,00 exclusief btw.

De snapshot bevat bedrijf-ID HS-C-18452, contact-ID HS-P-9033, Moneybird-contact-ID MB-77102, valuta EUR en betaaltermijn 30 dagen. De drie regels komen uit de goedgekeurde quote:

De factuur komt uit op €9.075,00 inclusief btw. De dealwaarde en de regels kloppen dus op netto-niveau. Dat is nog geen vrijgave.

Bron en match. De stagingrecord krijgt case-sleutel hubspot:HS-1042:acceptatie:MB-ADMIN-01 en versie 1. De relatiekaart wijst naar Moneybird-contact MB-77102. De juridische naam, het factuuradres en het land matchen. Er is geen tweede kandidaat.

Write. De flow maakt een Moneybird-verkoopfactuur als draft met de drie regels, 21%-tax-rate-ID en omzetrekening per regel. De Moneybird-response levert MB-INV-2026-0815. De flow slaat die ID op en leest de factuur opnieuw uit. De drie regels, €7.500,00 netto, €1.575,00 btw en €9.075,00 totaal kloppen.

Vrijgave. Finance ziet de HubSpot-snapshot, opleverdocument ACC-2026-1017, de relatiekeuze, de payloadhash en de read-back. Finance keurt versie 1 goed. Pas daarna wordt de factuur verzonden. HubSpot krijgt Moneybird-factuur-ID MB-INV-2026-0815 en factuurstatus sent. De deal blijft Gewonnen; dat veld krijgt geen nieuwe betekenis.

Deelbetaling. Op 5 november registreert Moneybird een betaling van €4.537,50. De synchronisatie leest de factuur terug en zet de betaalstatus op gedeeltelijk betaald, het betaalde bedrag op €4.537,50 en het openstaande bedrag op €4.537,50. Op 18 november komt een tweede betaling binnen. De read-back toont dan €9.075,00 aan geldige geregistreerde betalingen, total_unpaid nul en state paid; pas dan krijgt HubSpot de CRM-status betaald.

Credit of refund. De klant betwist later de bedieningsmodule van €3.800,00 exclusief btw. De bijbehorende creditfactuur of echte refund bedraagt €4.598,00 inclusief 21 procent btw. Als het bedrag nog niet is teruggestort, blijft de CRM-status refund in behandeling. Na goedgekeurde creditfactuur wordt die gecrediteerd of verrekend; na een echte geldterugstorting wordt de CRM-status terugbetaald. De flow maakt geen nieuwe factuur en zet de deal niet terug naar Open: de oorspronkelijke Moneybird-factuur blijft intact, de creditfactuur of refundcase is apart traceerbaar.

Stel dat de webhook voor de eerste betaling twee keer komt. De eerste push wordt opgeslagen onder zijn Idempotency-Key. De tweede push wordt herkend als dezelfde levering. De flow geeft opnieuw 200, maar maakt geen tweede betaling of nieuwe CRM-activiteit. Stel dat de Moneybird-write na het versturen van de request een timeout geeft. De case blijft write unknown; de hersteljob zoekt eerst naar de bestaande Moneybird-factuur op referentie, case-sleutel en contact voordat hij iets nieuws probeert.

Valkuil- en routevergelijking

Vergelijk dus de maandprijs én het herstelwerk. Een goedkope connector die geen dubbele factuur voorkomt is duurder zodra iemand een klant moet bellen over een verkeerde factuur. Omgekeerd is maatwerk overkill als één vaste regelset en een kleine queue je volledige proces beschrijven.

Een betrouwbare koppeling behandelt drie waarheden apart: de deal zegt wat sales heeft gewonnen, de factuur zegt wat Moneybird officieel heeft opgeslagen en de betaling zegt wat er financieel is ontvangen. De staginglaag bewaart hoe die waarheden aan elkaar zijn gekoppeld. De read-back bewijst dat de write gelukt is. De menselijke vrijgave bepaalt wanneer een voorstel een financiële handeling mag worden. Wie die grenzen laat staan, hoeft bij een retry, deelbetaling of refund niet te gokken waar het geld gebleven is.