Qué hacen los webhooks
Un webhook se suscribe a un evento específico de la tienda. Cuando ocurre ese evento, Storeep envía inmediatamente los datos del evento a una URL que especifiques (tipo API) o a una dirección de correo electrónico que indiques (tipo E-mail). Los webhooks se usan comúnmente para integraciones de seguimiento de pedidos, sincronización con CRM, conversiones en plataformas publicitarias y notificaciones automáticas.
Para gestionar webhooks, ve a Configuración → Webhooks. Necesitas el permiso de configuración para ver o cambiar webhooks.
Límites de webhooks
- Máximo 20 webhooks por tienda. Si intentas agregar un número 21, aparece el error "You have reached the maximum of 20 webhooks per store".
- La lista muestra los webhooks más recientes primero, paginados de 40 en 40.
Crear un webhook
Haz clic en Agregar nuevo webhook, completa los campos a continuación y luego haz clic en Agregar.
Activar
Marcado por defecto. Cuando está marcado, el webhook está activo en el momento en que lo guardas y se envían los eventos correspondientes. Desmárcalo para guardar el webhook en estado desactivado y que no reciba nada. Puedes cambiar esto en cualquier momento editando el webhook.
Nombre
- Obligatorio. Máximo 50 caracteres.
- Una etiqueta descriptiva que se muestra en la lista, por ejemplo Facebook CAPI order created.
Tipo
- API: Storeep envía una solicitud HTTP POST con los datos del evento a tu URL.
- E-mail: Storeep envía un correo electrónico con los datos del evento a tu dirección.
Evento
El evento de la tienda que activa el webhook. Existen tres eventos:
- Session created: se crea una nueva sesión de visitante en tu tienda.
- Order created: se realiza un nuevo pedido.
- Order updated: cambia el estado o los datos de un pedido existente.
Importante: el tipo E-mail solo entrega Order created y Order updated. Si eliges E-mail con Session created, el webhook se guarda pero nunca envía nada. Usa el tipo API si necesitas el evento de sesión.
Formato
Solo hay una opción, Json: la carga útil se envía como un documento JSON.
URL (solo tipo API)
- Obligatorio cuando el tipo es API. Máximo 500 caracteres.
- El campo muestra un prefijo
https://para ti, así que ingresa solo el host y la ruta, por ejemploapi.example.com/events/order. Si pegas una dirección completa conhttps://ohttp://, el prefijo se elimina antes de guardar. - Marcadores dinámicos: puedes inyectar cualquier campo de los datos del evento en la URL usando la sintaxis de doble llave
{{field_name}}. Ejemplo:example.com/postback?cid={{fbclid}}&payout={{order_total}}. Los valores se codifican para URL, y un marcador cuyo campo no exista se resuelve como vacío. Esto te permite enviar datos de conversión directamente a una plataforma publicitaria sin un proxy. - La dirección se valida después de quitar los marcadores, así que una URL no válida muestra "The url you have entered is incorrect".
Dirección de correo electrónico (solo tipo E-mail)
- Obligatorio cuando el tipo es E-mail. Debe ser una dirección válida, máximo 127 caracteres.
Editar un webhook
Haz clic en cualquier fila para abrir el editor. Todos los campos son editables. El campo URL solo se rellena si el tipo guardado es API, y el campo de correo solo si el tipo guardado es E-mail. Haz clic en Guardar para aplicar. Guardar con Activar desmarcado desactiva el webhook sin eliminarlo.
Columnas de la lista de webhooks
- Nombre: la etiqueta con su fecha de creación.
- URL / E-mail: el destino.
- Tipo: API o E-mail.
- Evento: Session created, Order created u Order updated.
- Formato: Json.
- Estado: Activado o Desactivado.
Eliminar un webhook
Selecciona una o más filas y haz clic en Eliminar webhooks. La eliminación es permanente y detiene todas las entregas futuras para esa suscripción.
Entrega, reintentos y correos de fallo
Esta sección aplica a los webhooks de tipo API. Los webhooks de tipo E-mail se envían una sola vez y no tienen reintentos ni seguimiento de fallos.
Comportamiento de reintentos
- Cada solicitud tiene un tiempo de espera de 5 segundos. Si un destino devuelve un error 5xx, 429 (limitado por tasa) o no se puede contactar (error de conexión), la entrega se trata como un fallo temporal y se reintenta.
- Tras el primer fallo, Storeep reintenta con retroceso exponencial hasta 5 veces: aproximadamente 30s, 60s, 120s, 240s y luego 480s después. Tras el último intento, el evento se descarta.
- Una respuesta 4xx distinta de 429 (por ejemplo 404 o 403) se considera un fallo permanente. Storeep no lo reintenta, ya que un endpoint incorrecto o que rechaza no se corregirá solo.
- Si tienes varios webhooks para el mismo evento, un reintento solo reenvía a los que fallaron. Los endpoints que ya devolvieron éxito se omiten, así que no recibes entregas duplicadas.
Correo de notificación de fallo
- Storeep cuenta los fallos consecutivos por webhook. Tras 5 fallos consecutivos, el propietario de la tienda recibe un correo titulado "Action needed: your Storeep webhook is failing", en el idioma del propietario, con el nombre del webhook, destino, evento y el último código de estado HTTP.
- Recibes exactamente un correo por cada racha de fallos. No se envían más correos hasta que ese webhook se recupere.
- En cuanto una entrega vuelve a tener éxito, el contador de fallos se reinicia a cero y la notificación se reactiva, así que una futura racha rota puede volver a enviarte un correo.
Consejos y advertencias
- Puedes crear varios webhooks para el mismo evento, por ejemplo enviar Order created tanto a un CRM como a una plataforma publicitaria como dos entradas separadas.
- Si tu endpoint requiere autenticación, pon un token en la cadena de consulta de la URL, ya sea fijo o usando un
{{placeholder}}de los datos del evento, o colócalo detrás de un proxy que agregue la autenticación antes de reenviar. - Session created se activa por cada sesión única de visitante y puede tener alto volumen en tiendas concurridas. Solo suscríbete si tu endpoint puede manejar ese flujo, y recuerda que solo funciona con el tipo API.