Getting Started

At Auco, to give you full control over the integration with each created process, we offer a webhook system that allows you to receive notifications at each stage of every workflow, from start to finish.

For configuring the webhook, there are two ways, via the API and the web platform:

Creating from app.auco.ai:

You must be an admin or have admin permissions to configure this. From the platform, you can only create one webhook, which will be the 'default' webhook.

• Log in with your email and password.
• Go to your profile at www.auco.ai/profile
• Enter the development options
• At the bottom, you will find options to modify your webhook and authentication headers if needed.

Creating via the Auco API

Is it possible to have multiple webhooks?

🆕 Yes! Through the API you can create multiple webhooks. Each webhook must have an id. Your first webhook must have the id 'default', which is where all notifications will be sent by default; subsequent webhooks can have any id you prefer.

important

To define which webhooks will receive notifications for the process states, you must save the list of webhook ids during document creation.

Authentication

Include your private key in the Authorization header.

Authorization: prk_xxx...

Webhook Creation Parameters

Name	Type	Description
id	String required	Identifier name of the webhook, the first webhook must be default.
description	String optional	Description of the webhook's purpose.
url	String required	URL (valid URI) where the webhook notifications will be sent.
header	Object optional	Object { key, value } with the authentication header to send.
header.key	String conditional	Subfield of header. Required if header is sent: header key.
header.value	String conditional	Subfield of header. Required if header is sent: header value.

Where are they configured?

Webhooks are saved through the Update Organization endpoint (PUT /v1.5/ext/company), in the webhooks parameter. There you will find the complete request examples in Curl, Python and Node.js.

👉 See Update Organization.

Always send the complete list

The webhooks parameter replaces the existing configuration: you must send the complete list and always include the webhook with id: "default". To keep already created webhooks, include them in the request.

---

Response Time and Retries

Auco waits a maximum of 10 seconds for your endpoint's response. If your server does not respond within that window, Auco closes the connection and the notification is recorded as a timeout.

Those 10 seconds cover the whole request: DNS resolution, TLS handshake and the time your server takes to respond. An endpoint that averages 8 seconds is already at the limit.

Respond first, process afterwards

Return 200 as soon as you receive the notification and queue the heavy work —writing to your database, downloading the PDF, calling another service— in the background.

A handler that downloads files or calls a third party synchronously before responding easily exceeds the 10 seconds, and the notification is cut off even if your code finished correctly.

Retries

A notification counts as delivered only if your endpoint responds with a 2xx code. If it fails —by timeout, or because you respond 4xx or 5xx— Auco retries it up to 3 times, waiting a little longer each time:

Retry	When
1st	2 minutes after the failed attempt
2nd	4 minutes after the previous one
3rd	6 minutes after the previous one

After the third retry Auco stops trying and that notification is discarded: it is not sent again.

A 4xx does not cancel the notification

Responding with an error code does not tell Auco to drop the event: it triggers the same retry chain as a timeout. If your integration decides to ignore a status, respond 200 anyway and discard it on your side.

Your handler must be idempotent

A retry repeats the same notification. If your server did process it but responded late, you will receive it again. Use the process code together with the status to recognise a repeat, instead of creating a new record on every delivery.

The webhook is not the only path

Since a discarded notification is never resent, do not rely on the webhook alone to know where a process stands. You can query its state whenever you need it with Query Process.

---

⚠️ Error Responses

Code	Description
400	Missing the default webhook
401	Invalid or missing authentication