VICIfast
ENES

Revendedores: webhooks

Envíe eventos de sus clientes, como un nuevo registro o un servidor que entra en funcionamiento, a su propio CRM o sistema de facturación, y revise cada entrega.

Socios · 4 min de lectura

Revendedores: webhooks
El programa de revendedores está en pausa para nuevas inscripciones. Desde septiembre de 2026 no estamos aceptando nuevos revendedores y esperamos reabrirlo en el primer trimestre de 2027. Esta página es para los revendedores que ya forman parte del programa; nada ha cambiado en su cuenta.

Los webhooks permiten que sus propios sistemas se enteren de lo que sucede con sus clientes. Cuando ocurre algo, como que un cliente se registre o que un servidor entre en funcionamiento, enviamos un mensaje breve a una dirección web que usted elija, y su CRM, su herramienta de facturación o el chat de su equipo pueden actuar en consecuencia. Configurar esto es tarea de un desarrollador: comparta esta página con quien administre sus sistemas.

Qué necesita

  • Una cuenta de revendedor activa. Solo el propietario de la cuenta puede abrir las páginas de Revendedor.
  • Una dirección web de su lado que acepte solicitudes POST por https.
  • Un desarrollador que pueda agregar una pequeña verificación de que cada mensaje realmente proviene de nosotros.

Paso 1: Agregar un endpoint

  1. En la barra lateral, en Revendedor, haga clic en Webhooks.
  2. En Agregar endpoint, ingrese su URL del endpoint. Debe comenzar con https://.
  3. Si lo desea, asígnele una Etiqueta, como CRM webhook.
  4. En Eventos, marque los eventos que desea. Déjelos todos sin marcar para recibir todos los eventos.
  5. Haga clic en Agregar endpoint.
El formulario Agregar endpoint en la página Webhooks
El formulario Agregar endpoint en la página Webhooks

Paso 2: Copiar el secreto de firma

Justo después de agregar el endpoint, un recuadro verde muestra su secreto de firma. Haga clic en Copiar, guárdelo en un lugar seguro y luego haga clic en Listo. Se muestra una sola vez y no podemos volver a mostrarlo. Si lo pierde, agregue el endpoint de nuevo para obtener uno nuevo.

Trate el secreto de firma como una contraseña. Cualquier persona que lo tenga puede enviar mensajes que parezcan provenir de nosotros.

Paso 3: Enviar una prueba

  1. En Endpoints, busque su endpoint y haga clic en Prueba.
  2. Verá Evento de prueba en cola. Un mensaje de muestra CUSTOMER_SIGNED_UP marcado con "test": true se envía en la siguiente ronda de envío (consulte Tiempos y reintentos más abajo).
Un endpoint con sus botones Entregas, Prueba, Pausar y Eliminar
Un endpoint con sus botones Entregas, Prueba, Pausar y Eliminar

Paso 4: Revisar las entregas

  1. La parte superior de la página Webhooks muestra Entregadas (24 h), Reintentando (24 h) y Agotadas (24 h) para todos sus endpoints.
  2. Haga clic en Entregas en un endpoint. Use los recuadros Todo, Entregadas, Reintentando y Agotadas para filtrar. El registro conserva las 100 entregas más recientes.
  3. Haga clic en una entrega para abrirla. Verá el ID de entrega, el Último error y el Cuerpo de la última respuesta que devolvió su servidor (hasta 1,000 caracteres).
  4. Para una entrega agotada, primero corrija el problema de su lado y luego haga clic en Reintentar. Recibe una nueva serie de intentos y se envía en la siguiente ronda de envío.
El registro de entregas con sus recuadros de estado y una entrega abierta
El registro de entregas con sus recuadros de estado y una entrega abierta

Para desarrolladores: los mensajes

  • Cada mensaje es un POST con un cuerpo JSON: un id, el tipo de evento, una marca de tiempo y los detalles del evento.
  • Encabezados: X-Vicifast-Event (el tipo de evento), X-Vicifast-Signature (la firma) y X-Vicifast-Delivery (un ID de entrega único; úselo para omitir duplicados).
  • La firma es un HMAC-SHA256 del cuerpo sin procesar de la solicitud, con su secreto de firma como clave, en hexadecimal. Calcúlela sobre el cuerpo exactamente como se recibió: si su framework analiza primero el JSON, no coincidirá. En Node: crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex'), y luego compárela con el encabezado X-Vicifast-Signature.
  • Responda con cualquier estado 2xx en un plazo de 10 segundos. Cualquier otra cosa, incluido un tiempo de espera agotado, cuenta como un intento fallido.

Eventos que puede elegir

  • CUSTOMER_SIGNED_UP: un nuevo cliente se registró con su marca.
  • ORDER_PAID: se pagó el pedido de un cliente.
  • SERVER_PROVISIONED: el servidor de un cliente está listo.
  • SERVER_SUSPENDED y SERVER_TERMINATED: un servidor fue suspendido o eliminado.
  • TRIAL_ISSUED: usted otorgó una prueba.
  • AI_ANALYSIS_CHARGED y TTS_CHARGED: se cobró a un cliente el análisis de llamadas con IA o la conversión de texto a voz.
  • DOMAIN_VERIFICATION_FAILED: falló la verificación diaria de uno de sus dominios.

ORDER_CANCELED también se envía cuando usted rechaza un pedido de pago manual; solo lo reciben los endpoints que reciben todos los eventos.

Tiempos y reintentos

  • Los mensajes se envían una vez por hora, a los 7 minutos de cada hora. Un evento puede llegar hasta aproximadamente una hora después de ocurrir, así que considere los webhooks como una sincronización, no como una alerta instantánea.
  • Un mensaje fallido se reintenta, esperando más tiempo cada vez (desde minutos hasta 3 días), con un total de 8 intentos durante aproximadamente una semana. Después de eso se marca como agotado y se detiene hasta que usted haga clic en Reintentar.
  • Pausar detiene los envíos sin eliminar el endpoint, y los eventos que ocurren mientras está en pausa no se ponen en cola. Los mensajes cuyo envío corresponde mientras está en pausa se marcan como agotados con el error "endpoint disabled". Haga clic en Reanudar antes de eso si todavía desea recibirlos.
  • No puede editar la dirección de un endpoint. Para cambiarla, o para obtener un nuevo secreto, agregue un nuevo endpoint y luego Elimine el anterior. Al eliminarlo también se borra su historial de entregas y se descarta todo lo que siga pendiente.

Si algo sale mal

Preguntas frecuentes

› Todas las entregas fallan con HTTP 401 o 403.
Su verificación de firma está rechazando el mensaje. La causa habitual es calcular el hash de una copia del cuerpo analizada y vuelta a codificar en lugar de los bytes sin procesar. Corrija la verificación y luego haga clic en Reintentar en una entrega agotada para confirmarlo.
› Una entrega no muestra ningún código HTTP, solo un error.
No pudimos comunicarnos con su servidor en absoluto: la dirección no se resuelve, el certificado no es válido o se rechazó la conexión. El campo Último error indica cuál de estos casos es. Corríjalo y luego vuelva a intentarlo.
› Prueba dice "Error: endpoint no encontrado o inactivo".
El endpoint está en pausa. Haga clic en Reanudar y luego en Prueba otra vez.
› Reintentar dice "el endpoint está en pausa; reanúdelo primero desde la lista de webhooks".
Vuelva a Webhooks, haga clic en Reanudar en el endpoint y luego reintente la entrega.
› Los eventos llegan tarde.
Los mensajes se envían una vez por hora, así que una demora de hasta aproximadamente una hora es normal.
› Perdí el secreto de firma.
No se puede volver a mostrar. Agregue un nuevo endpoint con la misma dirección, actualice su código con el nuevo secreto y luego elimine el endpoint anterior.

Artículos relacionados

Etiquetas: reseller, webhooks, integrations