Verify First, Act Second: Signed Completion Webhooks for Skavio Agent Tools
An asynchronous processing API changes the shape of an integration: the hard part is no longer making a request, but deciding when a result is real. Skavio Agent Tools combines company-scoped jobs, scoped API keys, idempotent submissions and signed completion webhooks. The safe pattern is deliberately conservative. Submit once with a stable key, treat the webhook as an untrusted trigger, verify the signature before parsing, confirm job state through an authenticated call, then download the result. This guide keeps those steps separate and points to the published documentation for exact webhook mechanics.
Make the logical job the unit of truth
Skavio Agent Tools is a live company-scoped authenticated API for document, invoice, audio and data processing, with a shared prepaid credit wallet, self-service keys and asynchronous jobs. The integration should not be clever about job creation. One logical processing request should have one idempotency key, stored with the request context and reused after a timeout or retry. Persist the job identifier and the server quote at submission. A submission acknowledgement, an in-progress state and a completed result are not synonyms; only the authenticated job state should drive downstream work.
- Keep API keys server-side and scope each integration to the company that owns the job.
- Generate a durable idempotency key per logical submission; do not rotate it just because the network timed out.
- Store the job ID and quote context before waiting for a webhook.
- Treat fixed quotes and atomic reservations as processing controls, not as proof of customer revenue.
Verify the signature before parsing the payload
The webhook receiver should be designed as a security boundary. A request that reaches the endpoint is not yet trusted. Verify the signature using the documented scheme, then parse the body and route the event. Exact header names, signing algorithm, canonicalization, timestamp checks and replay controls are not inferred here; they belong in the Agent Tools documentation. If the signature scheme covers the raw body, retain the raw bytes before handing the request to a JSON middleware. Keep signing secrets out of logs, browser bundles, screenshots and support tickets.
- Read the documented signature header and compute the signature exactly as specified.
- Reject missing or invalid signatures before any state change or user-visible completion.
- Apply any documented timestamp and replay checks.
- Log request identifiers and error classes, not secrets or unnecessary document contents.
Treat a signed notification as a trigger, not a final state
A valid signature shows that a request was signed with the configured secret; it does not, by itself, prove that the job is complete, that the output is ready or that a credit reservation has become revenue. Use the authenticated job-status mechanism described in the documentation to confirm the current state. Check the company scope and job identifier. If the authenticated response still shows work in progress, record the notification and take no completion action. If it confirms completion, move to retrieval. Build an independent reconciliation path; assume neither message ordering nor exactly-once delivery unless the documentation states otherwise.
- Do not rely on a webhook alone for final completion.
- Confirm company scope and job identity before routing output.
- Use an authenticated status lookup as a recovery path when appropriate.
- Keep the notification record separate from accounting or revenue records.
Download with authentication, then reconcile the artifact
Download the artifact only through an authenticated result endpoint, as documented. Do not turn the company key into a browser credential or create an unauthenticated permanent file URL. Record enough provenance to reconcile later: company, job ID, idempotency key, quote reference, completion time and output format. The API's seven-day result retention window makes timely retrieval part of the design; an approval queue that sits for two weeks is not compatible with that window unless your own storage captures the output first. Operational limits also belong in the plan: 120 requests per minute, 100 upload files and 500 MB total upload per request, 100 queued company jobs and four active jobs.
- Use authenticated downloads and verify the result belongs to the expected company and job.
- Retrieve the result before the seven-day retention window closes.
- Keep debug logs free of API keys, signing secrets and unnecessary personal data.
- This is the production Agent Tools processing API, not the staging Invoice, Reporting or Research agent set; do not assume QuickBooks production posting is approved.