Novedades
Back to All

[API FE CRI] Validación de webhooks al crear o actualizar compañías

4 days ago by Alanube

Despliegue programado: lunes 26 de octubre de 2026, en sandbox y producción.

Ahora podrás comprobar que tu receptor de webhooks está disponible y acepta notificaciones antes de guardar su configuración. Esta validación se aplica al crear o actualizar una compañía, incluida la compañía principal.

¿Qué cambia?

Al configurar un webhook activo, Alanube enviará una petición de prueba a la URL indicada. La configuración se guardará únicamente si el receptor supera la validación.

Aplica a los eventos:

  • documents.emissionFinished
  • general.governmentStatusChanged

¿Cómo debe responder tu receptor?

Prepara tu endpoint para recibir una petición POST, con contenido JSON y los encabezados personalizados configurados en el webhook. El cuerpo de prueba será:

{
  "message": "Test message"
}

Tu receptor debe reconocer este mensaje como una prueba de conectividad, no como una notificación de un documento real, y devolver un código HTTP 2xx, por ejemplo 200 o 204.

Para que la validación sea exitosa:

  • Utiliza una URL HTTP o HTTPS accesible públicamente. Recomendamos HTTPS con un certificado válido.
  • Configura la URL final del receptor: no se aceptan redirecciones HTTP 3xx.
  • Evita URLs de localhost, redes privadas o destinos internos.
  • No incluyas usuario y contraseña dentro de la URL. Si el receptor requiere autenticación mediante encabezados, configúralos en el webhook.
  • Mantén la URL dentro del límite de 2048 caracteres.
  • Responde rápidamente: la comprobación dispone de un máximo de 10 segundos en total, compartido si se validan ambos webhooks en la misma operación.

¿Qué ocurre si la validación falla?

Si el receptor no está disponible, devuelve un código distinto de 2xx, presenta problemas de conexión o certificado, o supera el tiempo permitido, no se guardarán los cambios de esa solicitud.

Los fallos de validación del receptor devolverán HTTP 400, código AP1023, indicando el campo del webhook que debes revisar. Los errores de formato de la configuración seguirán utilizando AP0000.

Revisa la URL, la respuesta del receptor y sus requisitos de autenticación antes de volver a enviar la solicitud.

Webhooks inactivos y actualizaciones

  • Un webhook con status: "inactive" no recibirá la petición de prueba. La configuración enviada debe seguir cumpliendo los requisitos de formato y longitud.
  • Al reactivarlo con status: "active", se comprobará su configuración antes de guardar el cambio.
  • Una configuración nueva sin status se considera activa.
  • Si no incluyes webhooks en la actualización de una compañía, no se volverán a comprobar los que ya tenga configurados.
  • En documents.emissionFinished, las actualizaciones parciales conservan los valores omitidos, incluido el estado. Puedes desactivarlo enviando solo status: "inactive" o reactivarlo con status: "active" para validar la URL y los encabezados guardados.
  • En general.governmentStatusChanged, envía la URL al actualizar su configuración; si omites status, se considera activo.

¿Debes realizar algún ajuste?

Antes del despliegue, verifica que tu receptor acepte el mensaje de prueba anterior y responda con un código 2xx sin redirecciones. Si requiere encabezados de autenticación, asegúrate de incluirlos en su configuración.

Esta mejora no cambia el formato de las notificaciones habituales ni incorpora nuevos eventos. La prueba confirma la disponibilidad del receptor en el momento de configurar el webhook; no garantiza su disponibilidad futura.