Outbound communicatieframework
Het outbound communicatieframework beheert alle uitgaande communicatie vanuit ERP-NL naar externe partijen: API-integraties, SFTP-bestandsoverdracht, webhooks en cloudgebeurtenissen. Dit document beschrijft wat operators kunnen doen, welke schermen beschikbaar zijn, en hoe de operationele opvolging werkt.
Wat kun je met het outbound framework?
- Inloggegevens voor externe integraties (KvK, ING, SFTP) beheren zonder clustertoegang.
- De verbinding met externe diensten testen vanuit de UI.
- Alle uitgaande bezorgpogingen bewaken: status, foutcodes, herhaalpogingen.
- Mislukte bezorgingen opnieuw aanbieden, annuleren of opnieuw herstarten.
- Webhook-abonnementen aanmaken en beheren, inclusief verificatie van het eindpunt en configuratie van ontvangersauthenticatie.
- Gevoelige instellingen (API-sleutels, certificaten, wachtwoorden) veilig opslaan en roteren.
Alle schermen zijn uitsluitend toegankelijk voor platform-beheerders.
Schermen
| Scherm | Route | Doel |
|---|---|---|
| Connecties | /setup/integration/connections | Inloggegevens per integratie bekijken en bijwerken |
| Bezorgingen | /outbound/deliveries | Uitgaande bezorgpogingen bewaken en beheren |
| Webhooks | /setup/integration/webhooks | Webhook-abonnementen beheren |
Connecties
Het scherm Connecties binnen Integratiebeheer toont alle geconfigureerde outbound-integraties. Per integratie zie je welke instellingen opgeslagen zijn en kun je:
- een instelling toevoegen of bijwerken;
- een instelling verwijderen;
- een gevoelige waarde tijdelijk zichtbaar maken via Onthullen;
- de verbinding testen via Verbinding testen.
Gevoelige waarden
Wachtwoorden, API-sleutels, certificaten en tokens worden nooit in leesbare vorm opgeslagen of getoond. De weergave toont standaard ***. Klik op Onthullen om de waarde tijdelijk te tonen — het systeem haalt de waarde op via een beveiligde verbinding en toont deze alleen in de huidige sessie.
Verbinding testen
De knop Verbinding testen stuurt een proefverzoek naar de externe dienst met de opgeslagen inloggegevens. Het resultaat (geslaagd of foutmelding) wordt direct getoond zonder de pagina te verladen. Gebruik dit na het bijwerken van inloggegevens om te controleren of de integratie correct werkt.
Rotatie van inloggegevens
Werk de waarde bij via het formulier. De nieuwe waarde wordt direct gebruikt bij de volgende bezorgpoging — een herstart van de server is niet nodig. Voor ING ICC-adaptercertificaten worden PEM-waarden opgeslagen als onbewerkte tekst (zonder \n-ontsnapping).
Bezorgingen
Het scherm Bezorgingen toont alle rijen uit de bezorgtabel (outbound_deliveries). Je kunt filteren op transport, integratie, status en datumbereik.
Statussen
| Status | Betekenis |
|---|---|
PENDING | Aangemaakt, nog niet geprobeerd |
SENDING | Een worker verwerkt de bezorging op dit moment |
DELIVERED | De externe ontvanger heeft de bezorging geaccepteerd |
FAILED_RETRYABLE | Tijdelijke fout; wordt automatisch opnieuw geprobeerd |
FAILED_PERMANENT | Definitieve fout; vereist handmatige actie |
CANCELLED | Geannuleerd door beheerder of bedrijfslogica |
Acties per bezorging
| Actie | Wanneer beschikbaar | Effect |
|---|---|---|
| Opnieuw proberen | FAILED_PERMANENT of FAILED_RETRYABLE | Zet de rij terug naar PENDING met directe herpoging |
| Annuleren | Elke niet-definitieve status | Zet de rij naar CANCELLED; geen verdere pogingen |
| Opnieuw starten | Definitieve status (DELIVERED, FAILED_PERMANENT, CANCELLED) | Maakt een nieuwe bezorgrij aan op basis van de bestaande rij |
Elke actie wordt vastgelegd in het auditlogboek met de actor (beheerder) en het tijdstip.
Foutcodes
Veelvoorkomende foutcodes:
| Code | Oorzaak |
|---|---|
HTTP_STATUS | De externe dienst retourneerde een niet-verwachte HTTP-statuscode |
HTTP_ERROR | Netwerk- of verbindingsfout |
CIRCUIT_OPEN | De circuit breaker staat open na herhaalde fouten |
SUBSCRIPTION_NOT_ACTIVE | Het webhook-abonnement is niet actief |
MISSING_PAYLOAD | De bezorgrij heeft geen payload |
EXPIRED | De bezorging is verlopen (expires_at verstreken) |
Webhooks
Het scherm Webhooks beheert webhook-abonnementen: configuraties die bepalen naar welk eindpunt ERP-NL cloudbeveiligde berichten stuurt bij bepaalde bedrijfsgebeurtenissen.
Abonnement aanmaken
Vul in:
| Veld | Toelichting |
|---|---|
| Integratie | Interne naam voor de integratie, bijv. mijn-systeem |
| Eindpunt-URL | Het HTTPS-adres waar ERP-NL de berichten naartoe stuurt |
| Event-typen | Kommagescheiden lijst van events, bijv. nl.erp.factuur.goedgekeurd |
| Ontvanger-authenticatie | Hoe ERP-NL zich bij het eindpunt identificeert (zie hieronder) |
Na aanmaken stuurt het systeem een verificatieverzoek naar het eindpunt (challenge-response). Als het eindpunt antwoordt met het juiste token, wordt het abonnement direct actief. Anders blijft de status verificatie vereist en kan de beheerder het later opnieuw proberen.
Ontvanger-authenticatie
Naast HMAC-handtekeningverificatie (die altijd actief is) kan ERP-NL zich bij de ontvangende dienst authenticeren:
| Type | Wanneer te gebruiken |
|---|---|
| Geen | Publieke eindpunten of eindpunten die alleen de HMAC-handtekening controleren |
| API-sleutel | Eindpunten die een vaste sleutel in een header verwachten |
| Bearer-token | Eindpunten die een statisch Authorization: Bearer ... token verwachten |
| Basisverificatie | Eindpunten die HTTP Basic-authenticatie vereisen |
| OAuth2 Client Credentials | Eindpunten die een OAuth2-toegangstoken verwachten (token wordt automatisch opgeroepen en gecacht) |
De inloggegevens worden versleuteld opgeslagen in de integratie-instellingen en worden uitsluitend bij elke bezorgpoging opgehaald.
Handtekening verifiëren (ontvangerskant)
ERP-NL ondertekent elke webhook-aanvraag met HMAC-SHA256. De handtekening zit in de header:
X-Webhook-Signature-256: sha256=<hex>Verificatie aan de ontvangerskant (Python-voorbeeld):
import hmac, hashlib
def verify(secret: str, body: bytes, signature_header: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode(), body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature_header)Statusoverzicht
| Status | Betekenis |
|---|---|
| Actief | Berichten worden bezorgd |
| Verificatie vereist | Eindpunt nog niet geverifieerd; geen bezorgingen |
| Gepauzeerd | Bezorgingen tijdelijk uitgeschakeld door beheerder |
Acties
| Actie | Toelichting |
|---|---|
| Pauzeren / Hervatten | Schakelt bezorgingen tijdelijk uit of weer in |
| Verificeer nu | Start een nieuwe challenge-response verificatie |
| Geheim roteren | Genereert een nieuw ondertekeningsgeheim; het oude geheim wordt onmiddellijk ongeldig |
| Verwijderen | Deactiveert het abonnement (zet naar gepauzeerd) |
Bewaking en meldingen
Het systeem bewaakt automatisch:
- Definitief mislukte bezorgingen (
FAILED_PERMANENT) → paginamelding - Geen actieve worker > 5 minuten → paginamelding
- Hoog percentage herhaalpogingen → waarschuwing
- Wachtrij ouder dan de SLA-grens → waarschuwing
- Bezorging vastzittend in
SENDING→ waarschuwing
Bij een paginamelding is directe actie vereist. Controleer via het scherm Bezorgingen welke integratie problemen geeft.
Veelgestelde vragen
Wat doe ik als een bezorging definitief mislukt? Controleer de foutcode en de foutmelding op het scherm Bezorgingen. Herstel de onderliggende oorzaak (bijv. onjuiste inloggegevens bijwerken via Connecties, of een netwerkopdracht oplossen), en gebruik daarna Opnieuw proberen of Opnieuw starten.
Kan ik een bezorging ongedaan maken? Nee. Eenmaal bezorgd bij de externe ontvanger kan een bezorging niet worden teruggedraaid via ERP-NL. Neem contact op met de ontvangende partij als een bericht teruggedraaid moet worden.
Hoe weet ik of mijn webhook-eindpunt correct is geconfigureerd? Na aanmaken toont de status direct of de verificatie geslaagd is. Gebruik Verificeer nu om handmatig een nieuwe verificatie te starten. Controleer ook of het eindpunt de X-Webhook-Signature-256 header correct valideert.
Hoe roteer ik een API-sleutel? Werk de waarde bij via Connecties. De nieuwe sleutel wordt direct gebruikt bij de volgende bezorgpoging. Verwijder daarna de oude sleutel uit de K8s Secret in een volgende deploy.
Zijn opgeslagen geheimen beveiligd? Ja. Alle geheimen worden versleuteld opgeslagen (Fernet-symmetrische versleuteling). Ze worden nooit in leesbare vorm gelogd, opgeslagen in de bezorgtabel, of teruggestuurd naar de browser zonder expliciete actie van de beheerder.
Gepland ING Boekhoudkoppeling-profiel
#595/#596 voegt een afzonderlijke file-adapter toe binnen ICC. De algemene retry/restart-acties zijn daarvoor niet geldig na een mogelijk verzonden POST: unknown outcome blijft een exception; een bekende fileId wordt alleen gepolld. Ontvangen, geautoriseerd, uitgevoerd en bankboeking blijven afzonderlijke fasen. Dit gedrag is gespecificeerd, nog niet geïmplementeerd. Zie runbook voor voorbereiding en herstel.