Endpoints personalizados

Vincent Depassier · 17 de septiembre de 2026

Un endpoint personalizado es una URL pública que defines en API Gateway → Endpoints y que ejecuta una Automatización. Es la forma en que un sistema externo llega a tu workspace sin tener ninguna credencial de Praxsuite: el webhook de una pasarela de pago, un formulario en un sitio que no controlas, el callback de un socio.

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

/{workspaceId}/webhook/{endpointId} es la forma vieja de la misma ruta y sigue funcionando.

Auth: ninguna de las habituales. Ni API key ni JWT. Un endpoint autentica a quien lo llama con una firma HMAC que tú configuras — o, si no configuras ninguna, queda abierto a cualquiera que conozca la URL.

Dos modos

Un endpoint es Async o Sync, y se elige al crearlo. Esa es toda la diferencia de comportamiento.

En modo Async el sistema externo postea al endpoint, el gateway registra el evento y responde 200 de inmediato, y las automatizaciones suscritas corren después en segundo plano; que una falle no cambia ese 200. En modo Sync el gateway ejecuta la única automatización vinculada mientras quien llamó espera, y su nodo Response escribe el cuerpo, el content type y las cabeceras que recibe.

	Async ("webhook")	Sync ("endpoint")
Responde con	`200` de inmediato	Lo que haya producido el nodo Response de la automatización
Automatizaciones	Las que quieras, suscritas	Exactamente una, asignada en la vista Gateway
Quien llama espera la corrida	No	Sí
Para qué	Recibir eventos	Servir una API propia

Mandar un evento

POST /{workspaceId}/endpoint/{endpointId}
Content-Type: application/json

El cuerpo llega tal cual a la automatización. No hay forma obligatoria: lo que postee quien manda es lo que ve la automatización, en {{request.body}}.

Async responde con el evento registrado:

{ "received": true, "eventId": "…" }

Las automatizaciones corren después, en segundo plano. Que una falle no cambia el 200 que quien llamó ya recibió; mira API Gateway → Logs y el historial de corridas de la automatización.

Sync mantiene la conexión abierta, ejecuta la única automatización vinculada, y devuelve exactamente lo que escribió su nodo Response — cuerpo, content type y las cabeceras personalizadas que haya puesto. El payload lo decide tu automatización; el gateway no lo envuelve.

El cuerpo del pedido tiene un tope de 10 MB. Más que eso es 413.

Verificación de firma

Se configura por endpoint: un algoritmo, un secreto, la cabecera a leer y un formato.

Algoritmos: HMAC-SHA256, HMAC-SHA512, o ninguno.

Formatos:

Formato	Qué se firma	Valor de la cabecera	Compatible con
Por defecto	El cuerpo crudo	Hex, opcionalmente con prefijo `sha256=` / `sha512=`	GitHub y la mayoría de los webhooks genéricos
Timestamp-punto-payload	`{timestamp}.{cuerpo}`	`t={timestamp},v1={hex}`	Stripe, Slack

El nombre de la cabecera lo eliges tú, así que un endpoint puede leer X-Hub-Signature-256, Stripe-Signature, o lo que use quien manda.

Una firma inválida es 401. Un endpoint configurado para verificar pero al que le falta el secreto es 500, no un pase silencioso.

Verificación por desafío

Varias plataformas verifican la URL de un webhook antes de mandarle nada, llamándola con un desafío que esperan recibir de vuelta.

GET /{workspaceId}/endpoint/{endpointId}?hub.mode=subscribe&hub.verify_token=…&hub.challenge=…

Si el endpoint tiene un verify token configurado y coincide, la respuesta es hub.challenge como text/plain. Este es el handshake de Meta / Facebook / Instagram, y sirve para cualquier cosa que siga la misma convención.

Estado	Causa
`400`	`hub.mode` no es `subscribe`, o falta el token o el desafío
`403`	La verificación por desafío no está habilitada en este endpoint, o el token no coincide
`404`	No existe el endpoint, o no está activo

Caché de respuesta (sólo Sync)

A un endpoint Sync se le puede dar una política de caché, y entonces sus respuestas traen:

ETag: "…"
Cache-Control: …
X-Cache: HIT | MISS

Devuelve el ETag como If-None-Match y una entrada todavía vigente responde 304 Not Modified — sin correr la automatización, sin cuerpo, sólo cabeceras. Es el desenlace más barato que tiene este endpoint, y vale la pena que tu cliente lo pida.

El validador se manda también en un MISS, así que la primera respuesta ya se puede revalidar en la llamada siguiente en vez de volver a ejecutarse.

Una respuesta cuyo cuerpo sea una URL de archivo firmada no se cachea nunca: repetirla más tarde entregaría un enlace que ya venció.

Errores

La forma plana —{ "error": "…" }.

Estado	Causa
`400`	El pedido no se pudo aceptar como evento
`401`	Falló la verificación de firma
`403`	Verify token que no coincide, o verificación por desafío no habilitada
`404`	No existe el endpoint en este workspace, o está inactivo
`413`	Cuerpo de más de 10 MB
`500`	La verificación de firma está configurada pero falta su secreto

Ver también

API Gateway → Endpoints en la documentación, para crear uno, asignarle automatizaciones y configurar las reglas de origen que aplican a quien llame desde un navegador.