Configurar webhooks de cliente
Registra un receptor HTTPS para los eventos disponibles, protege el secreto de firma y utiliza el historial de entregas para diagnosticar fallos.
- Prepara el receptorUsa un endpoint HTTPS público que pueda recibir JSON.
- Suscríbete a eventosIntroduce el nombre, la URL y los tipos de evento del endpoint.
- Protege la firmaGuarda el secreto de un solo uso y valida las solicitudes entrantes.
- Comprueba las entregasUtiliza el estado y la respuesta para resolver problemas.
- Mantén el endpointRota los secretos o revoca los destinos que ya no necesites.
Eventos disponibles para clientes
El formulario de webhooks ofrece los eventos job finished, invoice issued y quota threshold. Selecciona solo los eventos que pueda procesar tu receptor. Los endpoints pertenecen al contexto personal o a la organización seleccionada. Los propietarios y administradores de la organización pueden gestionarlos; los miembros pueden verlos, pero no modificarlos. Un webhook envía notificaciones: el receptor no puede cambiar un pedido ni una factura por ese medio.
- Abre Webhooks en el contexto de organización previsto.
- Selecciona al menos un evento que admita tu receptor.
- Usa endpoints distintos para entornos diferentes.
Registrar un destino público
Crea un endpoint con un nombre de 2 a 120 caracteres, una URL válida y uno o más eventos de la lista. Se exige HTTPS y un nombre de dominio público. Se rechazan destinos locales, internos o con una IP privada, por lo que una URL de desarrollo local no funcionará. Envía el formulario cuando el receptor pueda aceptar JSON y devolver una respuesta HTTP correcta.
- Despliega un receptor en una dirección HTTPS pública y estable.
- Introduce su URL, un nombre claro y los eventos correspondientes.
- Envíalo una vez y corrige los errores de validación que aparezcan.
Validar mensajes firmados
Al crear el endpoint, el secreto de firma se muestra una sola vez. Las solicitudes incluyen los encabezados de evento, entrega, marca de tiempo y firma HMAC, además de un cuerpo JSON con el ID del evento, su tipo, la fecha de creación y los datos. Valida la firma usando la marca de tiempo y el cuerpo original exacto, aplica un intervalo razonable para la marca de tiempo y procesa los IDs duplicados de forma idempotente. No registres ni divulgues el secreto.
- Guarda el secreto en la configuración protegida del receptor.
- Valida la firma sobre el cuerpo de solicitud sin modificar.
- Registra los IDs de evento para evitar acciones duplicadas.
Consultar el historial de entregas
La página muestra las 50 entregas más recientes de todos tus endpoints. Las respuestas HTTP correctas aparecen como satisfactorias. Los errores del servidor y los límites de solicitudes pueden dar lugar a reintentos; otras respuestas fallidas pueden marcarse como fallidas de inmediato. Los intentos se detienen al alcanzar el límite. El historial incluye el estado HTTP y un cuerpo de respuesta o error limitado. Un evento puede no aparecer porque no se produjo o porque el endpoint no estaba suscrito a él.
- Revisa el evento, el número de intentos, el estado y el último error.
- Corrige la disponibilidad del receptor, la respuesta o los límites de solicitudes.
- Comprueba que una entrega posterior termina con estado satisfactorio.
Rotar el secreto de firma
La rotación sustituye el secreto del endpoint y vuelve a activarlo. Los receptores que solo usen el valor anterior rechazarán las nuevas solicitudes. Prepara el cambio de configuración del receptor, rota desde la fila del endpoint previsto, guarda el nuevo valor y despliega la actualización pronto. Si el secreto está comprometido, rótalo inmediatamente y revisa el historial por si hay actividad inesperada.
- Identifica las instancias del receptor y prepara un despliegue seguro.
- Rota el endpoint y guarda el secreto que se muestra una sola vez.
- Confirma que una entrega esperada posterior se completa correctamente.
Sustituir o revocar endpoints
Los controles de cliente permiten crear, rotar y revocar; no ofrecen una opción para editar la URL o los eventos. Para cambiar cualquiera de ellos, crea un endpoint de sustitución, comprueba que recibe los eventos correctos y después revoca el anterior. La revocación detiene las entregas futuras y marca el endpoint como inactivo. Úsala para destinos retirados o secretos comprometidos y comprueba el estado en la lista.
- Crea un endpoint de sustitución con la URL o los eventos corregidos.
- Confirma que la nueva entrega se completa correctamente.
- Revoca el endpoint anterior y verifica que está inactivo.
Preguntas frecuentes
¿Qué eventos se ofrecen?
Job finished, invoice issued y quota threshold.
¿Puedo usar HTTP sin cifrar?
No. Se exige una URL HTTPS pública.
¿Puedo volver a ver el secreto?
No. Rota el endpoint para generar otro secreto.
¿Por qué está pendiente una entrega?
Un error temporal del servidor o un límite puede provocar reintentos.
¿Por qué falló una entrega?
Consulta la respuesta y el historial de reintentos.
¿Puedo editar el endpoint?
No. Crea y verifica otro endpoint y revoca el anterior.