Endpoints

Un endpoint es una URL que ejecuta una de tus automatizaciones cuando alguien le hace POST.

Eso cubre las dos cosas que toda integración termina necesitando: recibir eventos de otro servicio, y dejar que otro servicio te haga una pregunta y reciba una respuesta. En Praxsuite son el mismo objeto, separados por un solo ajuste.

Se administran en API Gateway → Endpoints.

La URL

Cada endpoint tiene su propia dirección, con su id en la ruta:

POST https://gateway.praxsuite.com/{workspaceId}/endpoint/{endpointId}

No interviene ninguna API key. Es la única parte del gateway que no autentica con una credencial — tiene que ser así, porque quien llama es Stripe, o Meta, o un formulario de tu sitio, y ninguno va a sostener una key tuya. La autenticación es por firma, que es la página siguiente.

La ruta vieja /webhook/{endpointId} sigue funcionando y significa exactamente lo mismo. Preferí /endpoint/ en todo lo nuevo.

Dos modos

La decisión más importante, y no es reversible a los ojos de quien llama: cambia lo que recibe.

Async es para eventos que ya pasaron. Un pago se aprobó, llegó un mensaje, un envío se movió. Quien manda no quiere tu opinión, quiere un acuse — y va a reintentar si te demorás. Responder al instante y trabajar después es lo que mantiene tranquila su lógica de reintentos.

Sync es para preguntas. Un precio, una validación, una consulta. Quien llama está esperando la respuesta, así que la respuesta es el punto.

La semántica de fallas es la distinción real. En Async una automatización rota es invisible para quien manda: recibió su 200 y siguió, y el único rastro está en tu historial de eventos. En Sync una automatización rota también es problema de quien llama. Elegí Async cuando quien manda no debe quedar bloqueado por tus bugs; elegí Sync cuando quien manda necesita enterarse.

Async: recibir eventos

1. Creá el endpoint y copiá su URL.

2. Pegala en la configuración de webhooks del otro servicio.

3. Configurá la verificación de firma — ver Seguridad de endpoints.

4. Desde la vista Automatizaciones, suscribí una o varias a ese endpoint.

Cada llamada se guarda como evento antes de que corra nada, con el cuerpo, los headers, el estado y la duración. Ese historial es desde donde depurás: un webhook que "no hizo nada" es o un evento que nunca llegó, o un evento que llegó y un suscriptor que falló, y la lista de eventos te dice cuál en segundos.

Como la suscripción es de muchos a uno, agregar una segunda reacción a un evento entrante nunca implica volver a tocar la configuración de quien manda.

Sync: responder una pregunta

Enlazá exactamente una automatización, y su nodo Response es lo que recibe quien llama.

   llamador ──POST──▶ endpoint ──▶ automatización enlazada ──▶ nodo Response
                                                                    │
   llamador ◀────── cuerpo, content type, estado ◀──────────────────┘

Requisitos, los tres:

• La automatización tiene que estar Activa.

• Tiene que tener una versión publicada.

• Esa versión tiene que contener un nodo Response.

Si falta cualquiera, la llamada falla en vez de colgarse. La salida del nodo Response se devuelve tal cual con su propio content type, así que un endpoint puede responder JSON, texto plano, XML — lo que espere quien llama.

Timeout

SyncTimeoutSeconds viene en 30 y es por endpoint. Pasarse devuelve 504 Gateway Timeout a quien llama.

Ponelo en lo que quien llama realmente tolera, no en el máximo. Un formulario de navegador que tarda 30 segundos es una mala experiencia sin importar lo que permita el gateway; 5 a 10 segundos es un techo más honesto, y llegar a él te avisa que ese trabajo va en modo Async con un callback, no en una conexión sostenida.

Caché de respuestas

Un endpoint puede cachear lo que devuelve, para que llamadas idénticas repetidas se salteen la automatización por completo.

Los defaults son 30 segundos de TTL y 500 entradas.

`None` es el único ajuste correcto para un endpoint que escribe algo. Cachear un efecto secundario significa que el segundo llamador recibe la respuesta del primero y su escritura nunca ocurre.

Dos detalles que conviene saber:

• El cuerpo del request siempre forma parte de la clave de caché. Dos llamadores que mandan payloads distintos nunca comparten respuesta cacheada — que es lo que hace seguro cachear endpoints que identifican a quien llama dentro del cuerpo, la forma habitual acá.

• `CacheVaryHeaders` agrega headers puntuales a esa clave. Los valores se hashean en la clave, nunca se guardan.

Para WriteInvalidated e Hybrid, las tablas que invalidan el caché se derivan solas del grafo publicado de la automatización enlazada. Definilas a mano solo para corregir una derivación que salió mal — y acordate de que el TTL sigue siendo tu red para lo que el grafo no puede ver, como una lectura HTTP externa.

Quien mande If-None-Match recibe 304 Not Modified si ya tiene el cuerpo actual. Es el resultado más barato posible: sin correr la automatización, sin payload, solo headers.

Tamaño del payload

El límite sale de tu plan, y un cuerpo demasiado grande se rechaza con 413 antes de llegar a la automatización. La respuesta dice el límite real en megabytes, así que no hay que adivinar.

Activo e inactivo

Desactivar un endpoint hace que responda como si no existiera. La definición, su configuración de firma y todo su historial de eventos quedan — que es lo que querés para una integración retirada que quizás todavía tengas que explicar.

Cómo elegir, en una línea

¿Quien llama está esperando una respuesta? Sync. ¿Quien llama te está avisando que algo pasó? Async.

Todo lo demás — firma, orígenes, caché, timeout — se desprende de eso.

Siguiente

• Seguridad de endpoints — verificación de firma, el handshake de challenge y las reglas de origen.