Integraciones y entrada de documentos Útil

Configurar avisos por webhook

2:15 Tutorial 3.9

Un webhook manda al servidor de la integración un aviso firmado cuando ocurre un hecho, como una factura emitida o una respuesta de la AEAT, en lugar de consultarlo cada pocos minutos.

Antes de empezar

  • Plan Professional o superior. Con el plan Starter la pantalla muestra el candado del plan y no permite crear destinos.
  • Rol de titular o administrador del equipo.
  • Una clave activa con el permiso «Configurar avisos automáticos hacia un servidor propio»; se añade en Permisos de la clave.
  • Un servidor https accesible desde internet que compruebe la firma de cada aviso. No se admiten direcciones internas.

Paso 1. Abrir los avisos por webhook

En el menú lateral, Integraciones > API y desarrolladores > Webhooks, y pulsar Añadir destino (1).

Pestaña Webhooks con el botón Añadir destino (1) y el panel Cómo se activa un destino.

Paso 2. Elegir la clave y el servidor

  1. Clave de la integración (1): las claves sin el permiso de avisos salen deshabilitadas con «sin permiso de avisos».
  2. Dirección del servidor (2): obligatoria, comienza por https y admite hasta 500 caracteres.
Formulario Añadir destino de avisos con Clave de la integración (1) y Dirección del servidor (2).
Nota. Cada clave admite como máximo 10 destinos y no admite la misma dirección dos veces.

Paso 3. Marcar de qué avisar

En De qué quiere enterarse, marcar al menos un aviso (1): facturas y su estado ante la AEAT, cobros, documentos, modelos, gastos, pagos de IRPF, conciliaciones y baja próxima de la clave.

Lista De qué quiere enterarse con los avisos disponibles y varios marcados (1).
Importante. Un aviso solo llega si la clave tiene autorizado al cliente afectado y el permiso de lectura de ese recurso.
Atención. «La AEAT la ha registrado CON INCIDENCIAS» no es un éxito: la factura figura registrada con defectos y requiere revisión.

Paso 4. Crear el destino y copiar el secreto

  1. Pulsar Crear destino. Aparece «Destino creado y todavía apagado. …».
  2. En el recuadro Copiar el secreto ahora figura el secreto. Seleccionarlo, copiarlo y entregarlo al integrador.
Importante. El secreto se muestra una sola vez. Con él, el servidor comprueba que cada aviso viene de aquí. Si se pierde, hay que eliminar el destino y crearlo de nuevo.

Paso 5. Verificar el destino

  1. Con el servidor ya preparado, pulsar Verificar en la fila del destino.
  2. Se mandan dos avisos de prueba: uno con firma buena, que debe aceptar, y otro con firma falsa, que debe rechazar con un 401.
  3. Si cumple las dos condiciones, el estado pasa de Apagado a Activo.
Atención. Un servidor que acepta la firma falsa no está comprobando la firma: el destino no se activa hasta que lo corrija.

Paso 6. Revisar el historial y reenviar un aviso

  1. Pulsar Historial en la fila del destino. Cada entrega indica estado, intentos y última respuesta.
  2. En una entrega, pulsar Reenviar y confirmar con Sí, reenviar.
Nota. Los estados son Entregado, Reintentando, Sin entregar y Pendiente. Un aviso que falla se reintenta durante algo más de un día.
Atención. Si una entrega agota los reintentos sin ningún éxito entre medias, el destino se apaga solo y se avisa al equipo. Se reactiva con Verificar.
Nota. Eliminar detiene los avisos en el acto y conserva el historial de entregas.

Resultado

El destino figura como Activo y recibe los avisos marcados de los clientes autorizados de su clave. Cada entrega queda en su Historial.

Campos del formulario

Campo Qué admite Obligatorio Efecto
Clave de la integración Una clave activa con el permiso de avisos Sí Define de qué clientes llegan avisos.
Dirección del servidor URL https pública, hasta 500 caracteres Sí Destino al que se manda cada aviso firmado.
De qué quiere enterarse Casillas del catálogo de avisos Sí, al menos una Eventos que se envían a ese servidor.

Problemas frecuentes

«No hay ninguna clave activa. Crear una primero.»
Crear una clave antes de añadir el destino.
«La clave «{nombre}» no tiene el permiso de avisos. Añadirlo desde sus permisos y volver a intentarlo.»
Marcar el permiso de avisos en Permisos de la clave.
«Máximo 10 destinos de webhook por clave.»
Eliminar un destino en desuso o usar otra clave.
«Marcar al menos un aviso.»
Seleccionar al menos un aviso en De qué quiere enterarse.
«El servidor ha rechazado un aviso con firma VÁLIDA …»
El servidor rechaza avisos correctos. Revisar su comprobación de firma con el secreto del destino.
«El servidor ha ACEPTADO un aviso con firma inválida …»
El servidor no comprueba la firma. Corregirlo: sin ello, cualquiera podría mandarle avisos falsos.
«El servidor ha rechazado el aviso con firma inválida, pero respondiendo {n} en lugar de 401. …»
El servidor debe responder exactamente 401 a una firma falsa.
«No se ha podido contactar con el servidor (tiempo agotado, nombre que no resuelve o conexión rechazada). …»
Comprobar que la dirección responde desde internet y repetir Verificar.
El destino figura como «Activo, pero sin recibir».
El texto bajo la insignia indica el motivo: clave revocada o caducada, clave sin permiso de avisos o plan sin webhooks.

Continuar con

Consejo
Preparar y desplegar la comprobación de firma en el servidor antes de verificar: la prueba exige una respuesta correcta a cada uno de los dos avisos.
Anterior Conectar el Drive de un cliente Siguiente Consultar el consumo y el registro de llamadas

Prueba CopilotGestoria gratis

30 días gratis. Sube tu primera factura en 2 minutos.

Crear cuenta gratis