curl --request POST \
--url https://api.tupana.ai/v2/webhooks/ \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"master_entity_id": "ment_4829301923847",
"url": "https://mi-sistema.com/webhook/callback",
"events": [
"document.issued",
"document.delivered",
"document.rejected"
],
"secret": "mi-clave-secreta-super-segura",
"is_active": true,
"environment": "production",
"api_version": 2
}
'import requests
url = "https://api.tupana.ai/v2/webhooks/"
payload = {
"master_entity_id": "ment_4829301923847",
"url": "https://mi-sistema.com/webhook/callback",
"events": ["document.issued", "document.delivered", "document.rejected"],
"secret": "mi-clave-secreta-super-segura",
"is_active": True,
"environment": "production",
"api_version": 2
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
master_entity_id: 'ment_4829301923847',
url: 'https://mi-sistema.com/webhook/callback',
events: ['document.issued', 'document.delivered', 'document.rejected'],
secret: 'mi-clave-secreta-super-segura',
is_active: true,
environment: 'production',
api_version: 2
})
};
fetch('https://api.tupana.ai/v2/webhooks/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tupana.ai/v2/webhooks/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'master_entity_id' => 'ment_4829301923847',
'url' => 'https://mi-sistema.com/webhook/callback',
'events' => [
'document.issued',
'document.delivered',
'document.rejected'
],
'secret' => 'mi-clave-secreta-super-segura',
'is_active' => true,
'environment' => 'production',
'api_version' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tupana.ai/v2/webhooks/"
payload := strings.NewReader("{\n \"master_entity_id\": \"ment_4829301923847\",\n \"url\": \"https://mi-sistema.com/webhook/callback\",\n \"events\": [\n \"document.issued\",\n \"document.delivered\",\n \"document.rejected\"\n ],\n \"secret\": \"mi-clave-secreta-super-segura\",\n \"is_active\": true,\n \"environment\": \"production\",\n \"api_version\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tupana.ai/v2/webhooks/")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"master_entity_id\": \"ment_4829301923847\",\n \"url\": \"https://mi-sistema.com/webhook/callback\",\n \"events\": [\n \"document.issued\",\n \"document.delivered\",\n \"document.rejected\"\n ],\n \"secret\": \"mi-clave-secreta-super-segura\",\n \"is_active\": true,\n \"environment\": \"production\",\n \"api_version\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tupana.ai/v2/webhooks/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"master_entity_id\": \"ment_4829301923847\",\n \"url\": \"https://mi-sistema.com/webhook/callback\",\n \"events\": [\n \"document.issued\",\n \"document.delivered\",\n \"document.rejected\"\n ],\n \"secret\": \"mi-clave-secreta-super-segura\",\n \"is_active\": true,\n \"environment\": \"production\",\n \"api_version\": 2\n}"
response = http.request(request)
puts response.read_body{
"id": "dowe_2c9e5a1b7f3d0",
"url": "https://mi-sistema.com/webhook/callback",
"events": [
"document.issued",
"document.delivered",
"document.rejected"
],
"events_display": [
"Emitido",
"Entregado",
"Rechazado SII"
],
"secret": "mi-clave-secreta-super-segura",
"is_active": true,
"last_status_code": null,
"last_sent_at": null,
"success_rate": 0,
"last_delivery": null,
"created_at": "2025-01-13T11:00:00Z",
"updated_at": "2025-01-13T11:00:00Z",
"environment": "production",
"api_version": 2
}{
"error": "VALIDATION_ERROR",
"message": "<string>"
}{
"error": "VALIDATION_ERROR",
"message": "<string>"
}{
"error": "VALIDATION_ERROR",
"message": "<string>"
}Crear webhook
Crea un nuevo webhook para una entidad específica del usuario autenticado.
curl --request POST \
--url https://api.tupana.ai/v2/webhooks/ \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"master_entity_id": "ment_4829301923847",
"url": "https://mi-sistema.com/webhook/callback",
"events": [
"document.issued",
"document.delivered",
"document.rejected"
],
"secret": "mi-clave-secreta-super-segura",
"is_active": true,
"environment": "production",
"api_version": 2
}
'import requests
url = "https://api.tupana.ai/v2/webhooks/"
payload = {
"master_entity_id": "ment_4829301923847",
"url": "https://mi-sistema.com/webhook/callback",
"events": ["document.issued", "document.delivered", "document.rejected"],
"secret": "mi-clave-secreta-super-segura",
"is_active": True,
"environment": "production",
"api_version": 2
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
master_entity_id: 'ment_4829301923847',
url: 'https://mi-sistema.com/webhook/callback',
events: ['document.issued', 'document.delivered', 'document.rejected'],
secret: 'mi-clave-secreta-super-segura',
is_active: true,
environment: 'production',
api_version: 2
})
};
fetch('https://api.tupana.ai/v2/webhooks/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tupana.ai/v2/webhooks/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'master_entity_id' => 'ment_4829301923847',
'url' => 'https://mi-sistema.com/webhook/callback',
'events' => [
'document.issued',
'document.delivered',
'document.rejected'
],
'secret' => 'mi-clave-secreta-super-segura',
'is_active' => true,
'environment' => 'production',
'api_version' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tupana.ai/v2/webhooks/"
payload := strings.NewReader("{\n \"master_entity_id\": \"ment_4829301923847\",\n \"url\": \"https://mi-sistema.com/webhook/callback\",\n \"events\": [\n \"document.issued\",\n \"document.delivered\",\n \"document.rejected\"\n ],\n \"secret\": \"mi-clave-secreta-super-segura\",\n \"is_active\": true,\n \"environment\": \"production\",\n \"api_version\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tupana.ai/v2/webhooks/")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"master_entity_id\": \"ment_4829301923847\",\n \"url\": \"https://mi-sistema.com/webhook/callback\",\n \"events\": [\n \"document.issued\",\n \"document.delivered\",\n \"document.rejected\"\n ],\n \"secret\": \"mi-clave-secreta-super-segura\",\n \"is_active\": true,\n \"environment\": \"production\",\n \"api_version\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tupana.ai/v2/webhooks/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"master_entity_id\": \"ment_4829301923847\",\n \"url\": \"https://mi-sistema.com/webhook/callback\",\n \"events\": [\n \"document.issued\",\n \"document.delivered\",\n \"document.rejected\"\n ],\n \"secret\": \"mi-clave-secreta-super-segura\",\n \"is_active\": true,\n \"environment\": \"production\",\n \"api_version\": 2\n}"
response = http.request(request)
puts response.read_body{
"id": "dowe_2c9e5a1b7f3d0",
"url": "https://mi-sistema.com/webhook/callback",
"events": [
"document.issued",
"document.delivered",
"document.rejected"
],
"events_display": [
"Emitido",
"Entregado",
"Rechazado SII"
],
"secret": "mi-clave-secreta-super-segura",
"is_active": true,
"last_status_code": null,
"last_sent_at": null,
"success_rate": 0,
"last_delivery": null,
"created_at": "2025-01-13T11:00:00Z",
"updated_at": "2025-01-13T11:00:00Z",
"environment": "production",
"api_version": 2
}{
"error": "VALIDATION_ERROR",
"message": "<string>"
}{
"error": "VALIDATION_ERROR",
"message": "<string>"
}{
"error": "VALIDATION_ERROR",
"message": "<string>"
}¿Para qué se usa?
Crea un nuevo webhook para recibir notificaciones automáticas cuando ocurren eventos relacionados con documentos. Útil para:- Configurar notificaciones automáticas cuando se emiten documentos
- Recibir alertas cuando documentos son aceptados o rechazados por el SII
- Integrar con sistemas externos para procesamiento automático de documentos
- Monitorear el estado de entrega de documentos importantes
Qué hace
- Crea un nuevo webhook asociado a una entidad específica
- Configura la URL de callback que recibirá las notificaciones
- Define los eventos específicos que se notificarán (emitido, entregado, rechazado, pagado, cancelado)
- Permite configurar una clave secreta para verificar la autenticidad de las notificaciones
- Establece el estado inicial del webhook (activo o inactivo)
Ejemplos de uso
- Notificaciones de emisión: Configurar un webhook para recibir notificaciones cada vez que se emite un documento
- Integración con ERP: Conectar el sistema con un ERP externo para procesar documentos automáticamente
- Alertas de rechazo: Recibir notificaciones inmediatas cuando el SII rechaza un documento
Consideraciones Importantes
Entidad maestra
Debes especificar elmaster_entity_id de la entidad para la cual quieres crear el webhook. El usuario debe tener acceso a la entidad especificada.
Ambiente (environment)
both (default) recibe los documentos de producción y de sandbox; production o sandbox los separan sobre la misma empresa. Los eventos que no son de documento (credenciales, folios, cobros, programados) se entregan como producción.
Formato de identificadores (api_version)
2: todos los ids del payload son públicos (docu_…, ment_…), igual que la API v2. 1: ids enteros, el contrato de la API v1. Si lo omites, el default sigue la ruta: /v2/webhooks/ crea en 2 y /v1/webhooks/ crea en 1. Ver Identificadores en el payload.
Validación de URL
No puede existir un webhook con la misma URL para la misma entidad. Si intentas crear un webhook duplicado, recibirás un error de validación.Eventos disponibles
document.issued- Documento emitido exitosamentedocument.delivered- Documento entregado al receptordocument.rejected- Documento rechazado por el SIIdocument.paid- Documento pagadofolio_request.completed- Timbraje listo: el CAF se puede retirarfolio_request.failed- El SII no autorizó folios; no se consumió nadafolio_request.authorized_without_caf- El SII autorizó un rango y no entregó el archivodocument.unpaid- Documento revertido de pagado a no pagadodocument.cancelled- Documento cancelado
Authorizations
API Key para autenticación. Debe proporcionarse en el header Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo 'Api-Key ' seguido de tu API key)
Body
ID de la entidad maestra para la cual se crea el webhook
"ment_4829301923847"
URL del endpoint que recibirá las notificaciones
Lista de eventos a notificar
1document.issued, document.delivered, document.rejected, document.trace_updated, document.paid, document.unpaid, document.cancelled Clave secreta para verificar la autenticidad de las notificaciones
255Si el webhook está activo
De qué ambiente recibe eventos de documentos: both (default), production o sandbox. Los eventos que no son de documento (credenciales, folios, cobros, programados) se entregan como producción.
both, production, sandbox Formato de los identificadores que viajan en el payload. 2: todos los ids son public_id (docu_… documento, ment_… emisor/receptor, scdo_… programado, fir_… solicitud de folios, dowe_… webhook). 1: ids enteros, el contrato de la API v1. Si se omite, el default sigue la ruta de creación: /v2/webhooks/ crea en 2 y /v1/webhooks/ crea en 1 (desde la plataforma, la versión que ya usa la empresa). Los webhooks creados antes de octubre 2026 quedaron en 1: súbelos con PATCH o desde la plataforma.
1, 2 Response
Webhook creado exitosamente
ID único del webhook
"dowe_2c9e5a1b7f3d0"
URL del endpoint que recibe las notificaciones
Lista de eventos configurados
document.issued, document.delivered, document.rejected, document.trace_updated, document.paid, document.unpaid, document.cancelled Nombres legibles de los eventos
["Emitido", "Entregado", "Rechazado SII"]
Clave secreta para verificar notificaciones
Si el webhook está activo
Último código HTTP de respuesta
Fecha de último envío
Tasa de éxito de entregas (0-100)
0 <= x <= 100Información de la última entrega
Show child attributes
Show child attributes
Fecha de creación
Fecha de última actualización
De qué ambiente recibe eventos de documentos: both (default), production o sandbox. Los eventos que no son de documento (credenciales, folios, cobros, programados) se entregan como producción.
both, production, sandbox Formato de los identificadores que viajan en el payload. 2: todos los ids son public_id (docu_… documento, ment_… emisor/receptor, scdo_… programado, fir_… solicitud de folios, dowe_… webhook). 1: ids enteros, el contrato de la API v1. Si se omite, el default sigue la ruta de creación: /v2/webhooks/ crea en 2 y /v1/webhooks/ crea en 1 (desde la plataforma, la versión que ya usa la empresa). Los webhooks creados antes de octubre 2026 quedaron en 1: súbelos con PATCH o desde la plataforma.
1, 2 