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.
Crear un endpoint de webhook
- Ve a Admin → Configuración → Integraciones y abre la pestaña Webhooks.
- Haz clic en Añadir Webhook.
- Escribe un Nombre (de menos de 100 caracteres) y la URL del endpoint. La URL debe usar HTTPS.
- Opcional pero recomendable: en Secreto (opcional), haz clic en el botón de generar (Generar secreto) y copia el secreto para tu servidor. Consulta la sección sobre la firma más abajo.
- En Eventos, marca los eventos que quieres enviar. Marca el nombre de una categoría para seleccionar todos sus eventos.
- Deja Activo encendido para que el webhook empiece a recibir eventos.
- Haz clic en Crear Webhook.
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ó, 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.
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.
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:
- Lee el cuerpo sin procesar de la solicitud exactamente como llegó, antes de analizar el JSON.
- Construye la cadena firmada: el valor de
X-Mateflow-Timestamp, un punto (.) y después el cuerpo sin procesar. - Calcula un HMAC-SHA256 de esa cadena con tu secreto como clave y codifícalo en hexadecimal.
- Compáralo con la parte de
X-Mateflow-Signatureque va después desha256=, usando una comparación de tiempo constante. Rechaza la solicitud si no coinciden. - Si quieres, rechaza las solicitudes cuya marca de tiempo tenga más de unos minutos, para bloquear reenvíos maliciosos (replays).
Durante un periodo de transición, las solicitudes también llevan el propio secreto en un encabezado X-Webhook-Secret. Verifica la firma en lugar de confiar en ese encabezado.
Las solicitudes de la acción Trigger webhook de una regla de automatización funcionan de otra forma: no van firmadas y el secreto de la regla se envía tal cual en el encabezado X-Webhook-Secret. 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
En el menú Acciones del webhook:
- Probar Webhook envía una solicitud de prueba a tu endpoint.
- Deshabilitar detiene las entregas sin eliminar el webhook; Habilitar lo vuelve a activar.
- Editar cambia su nombre, URL, secreto o eventos.
- Eliminar borra el webhook y todos sus registros de entrega. No se puede deshacer.
La lista muestra el Estado de cada webhook, su Último disparo y los recuentos de Correctos y Fallidos. Un webhook muestra un estado de error cuando han fallado entregas recientes.
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. 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, hasta 3 veces. No hay ningún botón para reenviar una entrega tú mismo. Cada intento tiene su propia fila y un nuevo ID de entrega, mientras que 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, consulta la documentación para desarrolladores en mateflow.com/developers.
Artículos relacionados
¿Te resultó útil esta guía?