Vroeg of laat wil elk team dat documenten met de rest van de software praten: een bestand vanuit een script uploaden, een workflow starten vanuit een planner of direct horen wanneer een document klaar is met verwerken. AuraDoc biedt daarvoor twee aanvullende wegen. Met de REST API vragen je systemen AuraDoc iets te doen, en met webhooks laat AuraDoc je systemen weten dat er iets is gebeurd. Dit artikel loopt beide door, plus de beveiligingsdetails die in productie tellen.
API-sleutels en scopes
Alles begint met een API-sleutel. Maak er een aan via Dashboard › Settings › API keys, geef hem een naam en kies de scopes. Scopes beperken wat de sleutel mag, dus een sleutel die alleen bestanden uploadt heeft geen recht nodig om iets anders te beheren. Een sleutel kan geen andere sleutel maken met ruimere scopes dan zijn eigen, en de effectieve rechten zijn altijd die welke de sleutel en de rol van de persoon gemeen hebben, zoals beschreven in teamrollen en machtigingen. Verzoeken dragen de sleutel in de Authorization-header als bearer-token.
Dezelfde pagina toont gebruiksstatistieken per sleutel, zodat je ziet welke integratie druk is en welke stil is gevallen. In betaalde abonnementen kun je ook een limiet instellen voor één sleutel, handig als een luidruchtig script de andere niet mag hinderen. Lekt een sleutel uit, verwijder hem dan en maak een nieuwe; aan de kant van AuraDoc hoeft verder niets te veranderen.
Wat de API kan
De integratiepagina in de documentatie noemt het basisadres en bevat voorbeelden om te kopiëren. Nu kun je een document uploaden, AuraDoc een document vanaf een URL laten inlezen, een workflow-run starten en een handtekeningverzoek aanmaken, elk met één geauthenticeerd verzoek. Het zijn dezelfde handelingen als in het dashboard, dus een resultaat via de API verschijnt in de interface zoals elk ander.
Wie liever opvraagt dan aanroepen ontvangt, kan terecht bij trigger-endpoints die nieuwe documenten, voltooide workflow-runs en voltooide handtekeningen teruggeven, plus een catalogus die ze beschrijft. Tools die geen webhooks kunnen ontvangen, zoals spreadsheet-add-ons of no-codeplatforms, kunnen ze periodiek bevragen. De volledige referentie staat op de documentatiepagina over integraties.
Uitgaande webhooks
Voor meldingen in realtime open je Dashboard › Webhooks en voeg je een endpoint toe. Je kiest de gewenste gebeurtenissen uit een lijst, waaronder document aangemaakt, geclassificeerd en verwijderd, OCR en vertaling voltooid of mislukt, workflowgebeurtenissen, waarschuwingen over opslagquotum en handtekeninggebeurtenissen. Bij het opslaan toont AuraDoc het ondertekeningsgeheim één keer. Kopieer het meteen naar je ontvangende dienst; raak je het kwijt, roteer dan het geheim, er komt een nieuw geheim en de rotatie wordt vastgelegd in het auditlog.
Je kunt de payload vormgeven met een sjabloon van maximaal enkele duizenden tekens en die vóór het opslaan valideren. Een testknop stuurt een voorbeeldgebeurtenis met een test-header, zodat je kunt controleren of je endpoint bereikbaar is en de body leest voordat je erop vertrouwt. Elke webhook kan worden uitgezet zonder hem te verwijderen, handig tijdens onderhoudsvensters.
Handtekeningen controleren en storingen opvangen
Elke levering is ondertekend. AuraDoc berekent met jouw geheim een HMAC-SHA256 over het tijdstempel en de ruwe body en stuurt het resultaat mee in de handtekening-header, samen met headers voor de gebeurtenisnaam, de webhook-id, de leverings-id, het tijdstempel en het aantal pogingen. Je ontvanger moet de handtekening opnieuw berekenen uit de ruwe body, in constante tijd vergelijken en verzoeken met een te oud tijdstempel weigeren. Zo kan niemand een gebeurtenis naar je endpoint vervalsen, ook niet met kennis van het adres.
Endpoints vallen weleens uit, en AuraDoc houdt daar rekening mee. Mislukt een levering, dan wordt die automatisch opnieuw geprobeerd met toenemende tussenpozen, van vijf minuten tot zes uur. De leveringsweergave toont elke poging met de uitkomst, en na het oplossen van het probleem kun je handmatig opnieuw proberen. Omdat dezelfde leverings-id bij nieuwe pogingen wordt hergebruikt, kan je ontvanger duplicaten veilig negeren. Wil je webhooks combineren met bestanden van opslagproviders, lees dan cloudopslag en bewaakte mappen.