Most teams eventually want their documents to talk to the rest of their software: upload a file from a script, start a workflow from a scheduler, or be told the moment a document finishes processing. AuraDoc offers two complementary ways to do this. The REST API lets your systems ask AuraDoc to do something, and webhooks let AuraDoc tell your systems that something happened. This article walks through both, plus the security details that matter in production.
API keys and scopes
Everything starts with an API key. Create one in Dashboard › Settings › API keys, give it a name and choose its scopes. Scopes limit what the key can do, so a key used only to upload files does not need permission to manage anything else. A key cannot create another key with wider scopes than its own, and the effective permissions are always the ones shared by the key and by the person's role, as described in team roles and permissions. Requests carry the key in an Authorization header as a bearer token.
The same page shows usage statistics for each key, so you can see which integration is busy and which has gone quiet. On paid plans you can also set a rate limit for an individual key, which is useful when one noisy script should never starve the others. If a key leaks, delete it and create a new one; nothing else needs to change on the AuraDoc side.
What the API can do
The integrations page in the documentation lists the base address and shows ready-to-copy examples. Today you can upload a document, ask AuraDoc to ingest a document from a URL, start a workflow run and create a signature request, each with a single authenticated request. These are the same operations people perform in the dashboard, so a result created through the API appears in the interface just like any other.
If you prefer polling to receiving calls, there are trigger endpoints that return new documents, completed workflow runs and completed signatures, along with a catalog describing them. Tools that cannot receive webhooks, such as spreadsheet add-ons or no-code platforms, can check these endpoints on a schedule. The full reference and examples are on the integrations documentation page.
Outbound webhooks
For real-time notifications, open Dashboard › Webhooks and add an endpoint. You pick the events you care about from a list, which includes document created, classified and deleted, OCR and translation completed or failed, workflow events, storage quota warnings and signature-related events. When you save, AuraDoc shows the signing secret once. Copy it into your receiving service straight away; if you lose it, rotate the secret and a new one is generated, and the rotation is recorded in the audit trail.
You can shape the payload with a template, up to a few thousand characters, and validate it before saving. A test button sends a sample event, marked with a test header, so you can confirm your endpoint is reachable and parses the body before you depend on it. Each webhook can be switched off without deleting it, which helps during maintenance windows.
Verifying signatures and handling failures
Every delivery is signed. AuraDoc computes an HMAC-SHA256 over the timestamp and the raw body using your secret and sends the result in the signature header, together with headers for the event name, the webhook id, the delivery id, the timestamp and the retry count. Your receiver should recompute the signature from the raw body, compare it in constant time and reject requests whose timestamp is too old. Doing this means nobody can forge an event to your endpoint, even if they know its address.
Endpoints go down, and AuraDoc plans for that. When a delivery fails, it is retried automatically with growing delays, starting at five minutes and stretching to six hours. The deliveries view shows every attempt with its outcome, and you can trigger a retry by hand once you have fixed the problem. Because the same delivery id is reused for retries, your receiver can safely ignore duplicates. To combine webhooks with files arriving from storage providers, see cloud storage and watch folders.