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.

---

Identity Guard Signals

When the identity validation of a signer or of an AucoFace process goes through Auco's identity guard, the notification includes the signals field: the list of anti-fraud signals the guard recorded in that validation.

"signals": [
  { "code": "ALERT_FACE", "severity": "ALERT" },
  { "code": "ALERT_EMAIL_CHANGED", "severity": "INFO" }
]

severity	Meaning	Stopped the process
REPORT	Match against a block list.	Yes
ALERT	Fraud alert according to your organization's configuration.	Yes
INFO	Informative signal: it was recorded, but it did not block the process.	No

Decide by severity, not by code

The severity of the ALERT_* codes depends on each organization's configuration: the same code can arrive as INFO or as ALERT. Use severity to know whether the signal blocked.

signals comes in the signing (NOTIFICATION) and blocking (BLOCKED) notifications of documents and packages, and in every AucoFace notification. It is absent when the validation never reached the guard —for example, because the face comparison failed first— and when the list is empty. Treat a code you do not recognize as one more signal: new codes can appear.

code	Meaning
REPORT	The person is on a block list.
REPORT_EMAIL	The email is on a block list.
REPORT_PHONE	The phone is on a block list.
REPORT_FACE	The face is on a block list.
REPORT_DECEASED	The ID belongs to a deceased person.
REPORT_FACE_MISMATCH	The face does not match the enrolled one.
ALERT_FACE	The face belongs to another registered person.
ALERT_IDENTITY_MISMATCH	The data does not match the civil registry.
ALERT_IDENTIFICATION_NOT_FOUND	The ID does not exist in the civil registry.
ALERT_EMAIL_CHANGED	The person uses an email different from the one on file.
ALERT_PHONE_CHANGED	The person uses a phone different from the one on file.
ALERT_EMAIL	The email is already associated with another person.
ALERT_PHONE	The phone is already associated with another person.
ALERT_DEVICE	The device was used by several people.
ALERT_IP	The IP was used by several people.
ALERT_LOCATION	The location is unusual for this person.

---

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