Endpoints de webhook
Referencia de /v1/webhook-endpoints: crea, lista, consulta y borra las URLs que reciben los eventos de Constaia, con su secreto whsec_ y su modo.
Un endpoint de webhook es una URL tuya a la que Constaia envía eventos firmados: análisis terminados, lotes completados, saldo bajo. Puedes gestionarlos desde el panel o con esta API, útil para automatizar entornos (staging, previsualizaciones, despliegues por cliente).
Cómo recibir y verificar los eventos: Webhooks.
| Método y ruta | Qué hace |
|---|---|
POST /v1/webhook-endpoints | Crea un endpoint. Devuelve el secreto una sola vez. |
GET /v1/webhook-endpoints | Lista los endpoints de la cuenta. |
GET /v1/webhook-endpoints/{id} | Recupera uno. |
DELETE /v1/webhook-endpoints/{id} | Lo borra. |
Crear un endpoint
POST /v1/webhook-endpoints
Content-Type: application/json| Campo | Tipo | Descripción |
|---|---|---|
url | string | URL https:// que recibirá los eventos (máx. 2048 caracteres). Obligatorio. |
events | string[] | Eventos a los que te suscribes (al menos uno). Obligatorio. |
description | string | Texto libre para identificarlo (máx. 500 caracteres). Opcional. |
Eventos disponibles:
| Evento | Cuándo |
|---|---|
analysis.completed | Termina un análisis o clasificación que no pertenece a un lote. |
analysis.failed | Falla un análisis, también dentro de un lote. |
analysis.review_required | Un análisis termina con veredicto review (además de analysis.completed). |
batch.completed | Terminan todos los documentos de un lote. |
credits.low | El saldo baja del umbral configurado en el panel (solo live). |
* | Todos los eventos, incluidos los que se añadan en el futuro. |
curl https://api.constaia.com/v1/webhook-endpoints \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/constaia",
"events": ["analysis.completed", "analysis.review_required", "analysis.failed", "batch.completed"],
"description": "Producción"
}'{
"id": "we_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
"object": "webhook_endpoint",
"url": "https://example.com/webhooks/constaia",
"description": "Producción",
"events": ["analysis.completed", "analysis.review_required", "analysis.failed", "batch.completed"],
"status": "active",
"enabled": true,
"mode": "test",
"created_at": "2026-09-29T10:00:00.000Z",
"secret": "whsec_…"
}El secreto solo se muestra ahora
secret solo viene en la respuesta de creación. Guárdalo en tu gestor de secretos (por ejemplo, como CONSTAIA_WEBHOOK_SECRET). Constaia lo guarda cifrado y no vuelve a mostrarlo: si lo pierdes, borra el endpoint y crea otro.
Modo test y live
El endpoint hereda el modo de la clave con la que lo creas (mode: "test" o "live") y solo recibe eventos de ese modo. Para recibir eventos reales, créalo con una clave ck_live_. Es habitual tener dos endpoints: uno de test que apunta a staging y otro live que apunta a producción.
Errores
| HTTP | code | Cuándo |
|---|---|---|
400 | invalid_url | La URL no usa https. |
400 | invalid_json | El cuerpo no es JSON válido. |
422 | invalid_parameter | url no es una URL válida, events está vacío o contiene un evento desconocido (param indica cuál, p. ej. events.0). |
Admite Idempotency-Key: si reintentas una creación que no sabes si llegó con la misma clave y el mismo cuerpo, recibes la respuesta original (con el mismo secret) y la cabecera Idempotent-Replayed: true, sin crear un endpoint duplicado. Ver Idempotencia.
Listar endpoints
curl https://api.constaia.com/v1/webhook-endpoints \
-H "Authorization: Bearer $CONSTAIA_API_KEY"Devuelve todos los endpoints de la cuenta, de ambos modos (mira mode), del más reciente al más antiguo, sin secret:
{
"object": "list",
"data": [
{
"id": "we_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
"object": "webhook_endpoint",
"url": "https://example.com/webhooks/constaia",
"description": "Producción",
"events": ["analysis.completed", "analysis.review_required", "analysis.failed", "batch.completed"],
"status": "active",
"enabled": true,
"mode": "test",
"created_at": "2026-09-29T10:00:00.000Z"
}
],
"has_more": false,
"url": "/v1/webhook-endpoints"
}| Campo | Descripción |
|---|---|
id | Prefijo we_. |
url, description, events | Lo que indicaste al crearlo. |
status | active o disabled. Un endpoint desactivado no recibe eventos. |
enabled | true si status es active. |
mode | test o live. |
created_at | Fecha de creación. |
Recuperar y borrar
curl https://api.constaia.com/v1/webhook-endpoints/we_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
-H "Authorization: Bearer $CONSTAIA_API_KEY"
curl -X DELETE https://api.constaia.com/v1/webhook-endpoints/we_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
-H "Authorization: Bearer $CONSTAIA_API_KEY"{ "id": "we_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "object": "webhook_endpoint", "deleted": true }Al borrar un endpoint, las entregas pendientes hacia él dejan de reintentarse. Si no existe o ya se borró, 404 resource_missing.
Solo en el panel
La API v1 no tiene PATCH. Estas acciones se hacen en el panel, en la sección de webhooks:
- Editar la URL, los eventos o la descripción.
- Desactivar y reactivar un endpoint.
- Enviar un evento de prueba (
type: "test") para comprobar tu URL y tu verificación de firma. - Ver las últimas 100 entregas con su código de respuesta y reintentos.
Ejemplos con los SDK
import { Constaia } from "@constaia/sdk";
const constaia = new Constaia();
const url = "https://staging.example.com/webhooks/constaia";
const existing = (await constaia.webhookEndpoints.list()).find(
(e) => e.url === url && e.mode === (constaia.livemode ? "live" : "test"),
);
if (!existing) {
const endpoint = await constaia.webhookEndpoints.create({
url,
events: ["analysis.completed", "analysis.failed", "batch.completed"],
description: "Staging",
});
console.log("Guarda este secreto:", endpoint.secret);
}Siguientes pasos
Saldo y consumo
Referencia de GET /v1/balance y GET /v1/usage: créditos de packs, plan gratuito, reservas y consumo diario por tipo de documento, con ejemplos.
Webhooks
Recibe eventos firmados de Constaia: cuerpos de cada evento, verificación de la firma Standard Webhooks en siete lenguajes, reintentos, idempotencia y pruebas.