Webhook Targets

Seatmap.pro puede avisar a tus propios sistemas cuando cambian recintos, esquemas y mapas de asientos. Esta página describe cómo debe ser un destino de webhook y qué ocurre cuando falla una entrega.

Eventos

Evento	Se envía cuando
`venue.created`	Se crea un recinto.
`venue.updated`	Se modifica un recinto.
`venue.deleted`	Se elimina un recinto.
`schema.created`	Se crea un esquema.
`schema.updated`	Se modifica un esquema.
`schema.deleted`	Se elimina un esquema.
`seatmap.stored`	Se guarda un mapa de asientos.

Requisitos del destino

Breaking: a partir de la versión 1.70.0, un destino de webhook debe ser una dirección HTTPS pública. Un destino que no cumpla ambas condiciones se rechaza al guardarlo, y cualquier entrega hacia él se registra con el tipo de error TARGET_NOT_ALLOWED.

Un destino se acepta cuando:

La URL es un URI válido con host.
El esquema es https. Se rechaza http sin cifrar.
Todas las direcciones a las que resuelve el host son enrutables públicamente.

Se rechaza un host cuando alguna de sus direcciones es de loopback, link-local, site-local (rangos privados como 10.0.0.0/8, 172.16.0.0/12 y 192.168.0.0/16), multicast, CGNAT o está reservada de otro modo. También se rechazan las direcciones IPv6 de uso local único, así como las direcciones IPv6 mapeadas a IPv4 cuya dirección IPv4 subyacente esté bloqueada. Un host que no se puede resolver se rechaza igualmente.

Si tu endpoint no es público

Termina TLS en un nombre de host público y reenvía internamente desde ahí: basta con un proxy inverso o una pasarela de API delante de tu servicio. No esperes que un nombre de host interno funcione porque resuelva públicamente a una dirección privada; la comprobación se hace sobre la dirección resuelta, no sobre el nombre.

Las instalaciones propias que realmente necesiten entregar dentro de su propia red pueden poner seatmap.webhooks.allow-private-targets a true en el servicio de editor. Esto apaga la comprobación de direcciones, así que actívalo solo cuando toda la ruta de red esté bajo tu control.

Reintentos

Una entrega fallida se reintenta con retroceso exponencial, tres veces por defecto. Los valores por defecto son:

Ajuste	Por defecto	Significado
`timeoutMs`	`30000`	Tiempo de espera por intento.
`maxRetries`	`3`	Reintentos tras el primer intento.
`backoffInitialMs`	`1000`	Espera antes del primer reintento.
`backoffMultiplier`	`2.0`	Multiplicador aplicado a cada espera siguiente.
`retryOnHttpStatuses`	`500, 502, 503, 504`	Códigos que se reintentan.
`skipRetryOnHttpStatuses`	`400, 401, 403, 404`	Códigos que se consideran definitivos.

Los tiempos de espera agotados, los errores de red y los errores de conexión se reintentan. Un fallo TARGET_NOT_ALLOWED no se reintenta: el destino no es válido, así que esperar no sirve de nada. Tras el último reintento, el evento pasa a la lista de mensajes fallidos en lugar de descartarse en silencio.

Qué se guarda en cada intento de entrega

Cada intento registra el estado, el tipo de error y un fragmento del cuerpo de la respuesta, de modo que puedas ver por qué falló una entrega sin instrumentar tu propio endpoint.

Las cabeceras de respuesta que transportan credenciales se guardan como [redacted]: authorization, proxy-authorization, set-cookie, set-cookie2, www-authenticate, proxy-authenticate y x-amz-security-token. Si tu endpoint devuelve un token en alguna de estas cabeceras, no acaba en el registro de entregas.