Saltar al contenido

Guía

Configurar webhooks

Automatizaciones e integraciones · 7 min de lectura

Un webhook envía una solicitud HTTPS desde Mateflow a una URL que controlas cada vez que ocurre algo en tu comunidad, como la llegada de un nuevo miembro o de un pago. Usa los webhooks para mantener sincronizados un CRM, una herramienta de correo electrónico o tu propia app. Los configuras en Admin → Configuración → Integraciones → Webhooks.

Quién puede hacerlo: los propietarios y administradores. · Dónde: web (consola de administración). · Plan: los webhooks, y cuántos puedes crear, dependen de tu plan de la plataforma. Si tu plan deja de incluirlos, las entregas se detienen. Tus webhooks se conservan y vuelven a funcionar cuando mejoras el plan.

Crear un endpoint de webhook

  1. Ve a Admin → Configuración → Integraciones y abre la pestaña Webhooks.
  2. Haz clic en Añadir Webhook.
  3. Introduce un Nombre y una URL del endpoint HTTPS.
  4. Si quieres, genera un secreto de firma y cópialo al receptor. Consulta la verificación más abajo.
  5. Selecciona explícitamente al menos un evento. Busca o elige por categoría; Documentación del evento abre su referencia.
  6. Pulsa Crear Webhook. Los webhooks nuevos se guardan inactivos.
  7. Guarda, envía una prueba y activa el webhook cuando el receptor esté listo.

Si el botón Añadir Webhook muestra un aviso para mejorar el plan, tu plan no incluye webhooks o has alcanzado su límite de webhooks. Consulta Consultar el uso y los límites del plan.

Eventos de webhook a los que puedes suscribirte

Categoría Eventos
Miembros Miembro se unió, Miembro salió, Rol cambiado, Miembro suspendido (también se envía con los baneos), Miembro reincorporado, Miembro añadido a un grupo de acceso, Miembro retirado de un grupo de acceso
Contenido Publicación creada, Comentario creado, Publicación eliminada, Comentario eliminado
Pagos Pago recibido, Pago fallido, Suscripción creada, Suscripción renovada, Suscripción cancelada, Reembolso emitido

Los webhooks más antiguos pueden mostrar eventos que ya no están disponibles. Puedes quitarlos, pero no volver a añadirlos.

En configuraciones antiguas, una lista vacía significa todos los eventos, no ninguno. Puedes conservarla o elegir suscripciones explícitas. Los eventos no disponibles se mantienen al editar otros ajustes; para cambiar suscripciones, elimina los no compatibles y elige al menos uno actual. Si no carga el catálogo, reintenta antes de elegir o probar.

Cómo funcionan los eventos de webhook de los grupos de acceso

Miembro añadido a un grupo de acceso y Miembro retirado de un grupo de acceso (los grupos de acceso antes se llamaban niveles de miembro) se disparan cuando los grupos de un miembro cambian de verdad. Cada evento corresponde a un miembro y un grupo, e incluye el nombre de usuario y el correo electrónico del miembro, el nombre del grupo y el motivo del cambio: un administrador, una suscripción, una invitación, el grupo de acceso predeterminado o un grupo eliminado.

  • No se envía ningún evento de grupo de acceso antes de Miembro se unió, así que no se notifica el grupo predeterminado de un nuevo miembro al registrarse, ni los cambios mientras un miembro espera la aprobación.
  • Eliminar un grupo de acceso envía un evento de retirada por cada miembro que lo tenía. Estos eventos, y los que genera configurar un grupo predeterminado, pueden llegar unos minutos después.
  • Quitar un grupo que concede una suscripción envía una retirada y después una adición, porque la suscripción lo vuelve a añadir de inmediato. Consulta Añadir o quitar el grupo de acceso de un miembro.

Cómo funciona el evento de webhook «Miembro salió»

Miembro salió se envía una vez cuando alguien deja de ser miembro de tu comunidad, para que puedas quitarlo de tu CRM o de tu lista de correo. Se activa cuando:

  • un administrador usa Quitar de la comunidad o Anonimizar miembro;
  • el miembro elimina su cuenta. Una eliminación programada cuenta cuando termina el periodo de espera de 30 días, no cuando la solicita; si la cancela, no se envía nada;
  • tu política de retención de datos borra a un miembro inactivo. Se ejecuta cada noche, así que pueden llegar muchos eventos a la vez.

Cada evento incluye el nombre de usuario y el correo del miembro de antes de irse, aunque su cuenta se haya anonimizado, para que puedas encontrarlo en tu propio sistema. También indica cómo se fue y, si un administrador lo quitó o lo anonimizó, qué administrador. Si el administrador escribió una Nota interna (opcional) al quitar al miembro, la nota también se incluye.

Miembro salió no se envía cuando un miembro desactiva su cuenta, es suspendido o baneado (para eso está Miembro suspendido), sale de un espacio o nunca terminó de unirse. Los grupos de acceso que tenía un miembro que se va no envían Miembro retirado de un grupo de acceso.

Las apps conectadas cuya tarjeta muestra Enviando todos los eventos empiezan a enviar también Miembro salió, incluso a canales de Slack o Discord. Para dejarlo fuera, elige Editar ajustes y selecciona los eventos que se envían. Consulta Resumen de integraciones: API, webhooks y Zapier.

Verificar las firmas de los webhooks con la clave de firma

Cuando un webhook tiene un secreto, Mateflow firma cada solicitud con HMAC-SHA256 para que tu servidor pueda comprobar que viene de Mateflow y que no se ha modificado (verificación de la firma). Cada solicitud lleva dos encabezados:

  • X-Mateflow-Timestamp: cuándo se envió la solicitud, en segundos Unix.
  • X-Mateflow-Signature: sha256= seguido de la firma codificada en hexadecimal.

Para verificar una solicitud en tu servidor:

  1. Lee el cuerpo sin procesar de la solicitud exactamente como llegó, antes de analizar el JSON.
  2. Construye la cadena firmada: el valor de X-Mateflow-Timestamp, un punto (.) y después el cuerpo sin procesar.
  3. Calcula un HMAC-SHA256 de esa cadena con tu secreto como clave y codifícalo en hexadecimal.
  4. Compáralo con la parte de X-Mateflow-Signature que va después de sha256=, usando una comparación de tiempo constante. Rechaza la solicitud si no coinciden.
  5. Si quieres, rechaza las solicitudes cuya marca de tiempo tenga más de unos minutos, para bloquear reenvíos maliciosos (replays).

Las solicitudes de la acción Enviar webhook de una regla de automatización se firman de la misma forma cuando la regla tiene un secreto. Consulta Automatizar tareas con reglas.

Después de guardar, el secreto se oculta. Para conservarlo, deja el campo vacío al editar el webhook. Para rotarlo, genera uno nuevo y actualiza tu servidor al mismo tiempo.

Probar, pausar, editar o eliminar un webhook

Guarda antes de probar o abrir registros. En las acciones, abre el diálogo de prueba, elige un evento suscrito compatible con muestras y pulsa Enviar prueba. La muestra lleva test=true y se envía a la URL guardada, incluso si está inactivo. El receptor debe reconocer pruebas. Un 2xx solo confirma recepción HTTP, no que tu proceso termine. Revisa estado, respuesta y registros.

Activa tras probar; desactivar pausa entregas reales. Editar un webhook activo surte efecto al guardar. Eliminar borra también sus registros permanentemente. Si cambia la configuración, caduca el resultado anterior: vuelve a probar lo guardado.

Revisar las entregas y los reintentos de los webhooks

Abre la pestaña Registros de entrega para ver cada solicitud, su Estado HTTP, su Duración y su Origen. Para ver las entregas de un webhook, usa Filtrar por webhook. Haz clic en Ver detalles para ver la Carga de la solicitud y el Cuerpo de la respuesta completos. Los registros de entrega se conservan 30 días.

Cuando una entrega falla, Mateflow la reintenta automáticamente después de 1 minuto, 10 minutos, 1 hora y 6 horas. Las respuestas HTTP 429 y 408 también se reintentan; las demás respuestas 4xx no. Cuando se agotan los reintentos, o con una respuesta 4xx que no se reintenta, el propietario y los administradores reciben un correo electrónico, como máximo uno al día por cada webhook.

Para volver a enviar una entrega tú mismo, haz clic en Reenviar en su fila. Envía el mismo cuerpo, firmado de nuevo, a la URL actual del webhook. Actualiza la página para ver el resultado como una fila nueva. Un webhook eliminado o desactivado no puede reenviar. Cada intento tiene su propia fila. Un reintento automático recibe un nuevo ID de entrega, Reenviar conserva el original y el ID de evento se mantiene, así que las filas que comparten un ID de evento son intentos del mismo evento. Las entregas pueden llegar más de una vez o desordenadas, así que haz que tu servidor elimine los duplicados según el ID de evento. Para los campos de la carga y ejemplos de código, haz clic en Abrir documentación en la tarjeta Referencia de webhooks para desarrolladores de la pestaña Webhooks, o ve a mateflow.com/developers/webhooks. Puedes enviar ese enlace a tu equipo de desarrollo.

Los registros filtran por evento, resultado, webhook, fechas, Fuente y Plataforma. Las métricas respetan el ámbito y período seleccionados y cuentan intentos HTTP con pruebas, reintentos y reenvíos, no eventos únicos. Se muestra historial disponible y retención. Los totales de configuración son una instantánea aparte de webhooks activos, inactivos y activos con fallos recientes.

Artículos relacionados

¿Te resultó útil esta guía?

Volver a las guías

¿No encuentras lo que necesitas?

Si eres miembro de una comunidad, sus administradores son quienes pueden ayudarte. Si estás creando o gestionando una en Mateflow, nuestro equipo puede ayudarte.