Los equipos de marketing e ingeniería se ocupan de los datos de clics en silos. Los informes llegan con horas de retraso. Las exportaciones manuales introducen errores. Las decisiones se toman sobre la base de información obsoleta.
Los webhooks de Rebrandly entregan datos de eventos de clics a sus sistemas dentro de los 10 segundos de cada interacción. Los análisis se actualizan en tiempo real. Las automatizaciones se activan mientras la intención del usuario está activa. Los equipos ven el contexto completo de la campaña sin tener que iniciar sesión en varias plataformas.
En comparación con las encuestas: En lugar de comprobar repetidamente si hay nuevos clics, los webhooks ofrecen eventos a medida que ocurren: menos llamadas a la API, sin demoras en las encuestas y menores costos de infraestructura.
En comparación con las exportaciones por lotes: Las exportaciones manuales significan recordar extraer datos, convertir formatos de archivo y cargarlos en los sistemas de destino. Los webhooks automatizan este flujo de trabajo y reducen la entrada manual de datos en un 95%.
Esta guía cubre los patrones de implementación, seguridad e integración para los desarrolladores que crean flujos de trabajo automatizados con la infraestructura de webhooks de Rebrandly.
La carga útil del webhook
Cada vez que alguien hace clic en el enlace de tu marca, Rebrandly envía un HTTP POST a tu punto final con esta carga JSON:
{
"data": [
{
"timestamp": "2025-10-25T02:36:47.132Z",
"client": {
"agent": {
"browser": {
"name": "chrome-mobile",
"version": "121.0.0.0"
},
"os": {
"name": "android",
"version": "android-10"
},
"device": {
"name": "smartphone"
}
},
"geo": {
"country": "US",
"region": "CA",
"city": "San Francisco"
}
},
"route": {
"id": "12345abcde",
"slashtag": "product-launch",
"createdAt": "2023-08-31T04:13:48.385",
"domain": {
"id": "8f104cc5b6ee4a4ba7897b06ac2ddcfb",
"raw": "brand.link",
"zone": "link.brand"
},
"destination": {
"raw": "https://example.com/landing-page",
"protocol": "https",
"hostname": "example.com",
"path": "/landing-page"
}
}
}
],
"key": "userId_32f5164718384fcda6503f550295885e-configId_db2a7cdeb91f4a2b9"
}
Encabezados de solicitud:
- Tipo de contenido:
aplicación/json - X-Rebrandly-Secret: your_secret_key (para autenticación)
Qué hay en la carga:
- marca horaria: marca horaria ISO 8601 UTC. Utilícela para ordenar los eventos si llegan fuera de secuencia.
- client.agent: navegador, sistema operativo, tipo de dispositivo. Bueno para la detección analítica y de bots.
- client.geo: país, región, ciudad. Se usa para análisis geográficos o localización.
- client.location: datos geográficos con códigos de país en formato ISO 3166-1 A-2 (por ejemplo, «nosotros», «eso»). Los códigos de región utilizan el formato ISO 3166-1 alfa-2. La ubicación se determina mediante la dirección IP.
- ruta: ID de enlace, etiqueta diagonal (la mitad posterior de tu enlace corto), dominio, URL de destino. Conecta los clics con campañas específicas.
- clave: identificador único en formato `RB-Clicks-Stream-1-yyyy-MM-DD-HH-MM-SS- (GUID) `. Esto es más útil para que Rebrandly encuentre rápidamente el clic si lo necesita.
Implementación básica
Este es un punto final mínimo de webhook que valida el secreto y almacena los eventos:
# Python/Flask example
from flask import Flask, request, jsonify
import os
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def webhook_handler():
# 1. Validate the secret key
expected_secret = os.environ.get('apikey')
received_secret = request.headers.get('apikey')
if expected_secret != received_secret:
return jsonify({'error': 'Unauthorized'}), 401
# 2. Get the payload
event_data = request.get_json()
# 3. Process it (store, forward, trigger workflows)
for event in event_data['data']:
print(f"Click at {event['timestamp']}")
print(f"Link: {event['route']['slashtag']}")
print(f"Location: {event['client']['geo']['city']}")
# Save to database, call other APIs, etc.
# 4. Return success quickly (within 30 seconds)
return jsonify({'status': 'received'}), 200
if __name__ == '__main__':
app.run(port=5000)
// Node.js/Express example
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhook', (req, res) => {
// 1. Validate the secret key
const expectedSecret = process.env.REBRANDLY_SECRET_KEY;
const receivedSecret = req.headers['apikey'];
if (expectedSecret !== receivedSecret) {
return res.status(401).json({ error: 'Unauthorized' });
}
// 2. Get the payload
const eventData = req.body;
// 3. Process it
eventData.data.forEach(event => {
console.log(`Click at ${event.timestamp}`);
console.log(`Link: ${event.route.slashtag}`);
console.log(`Location: ${event.client.geo.city}`);
// Save to database, call other APIs, etc.
});
// 4. Return success quickly
res.status(200).json({ status: 'received' });
});
app.listen(5000, () => {
console.log('Webhook listener running on port 5000');
});
Sus requisitos de terminales:
- Aceptar solicitudes HTTP POST
- Validar el encabezado apikey
- Responda en 5 segundos (devuelva 200-299 códigos de estado si tiene éxito)
- Sea accesible a través de HTTPS
- Gestiona las cargas útiles de JSON
Información crítica sobre confiabilidad
No volvemos a intentar las entregas fallidas. Cada evento se envía una vez. Si su terminal está inactivo o devuelve un error, ese evento ha desaparecido.
Es posible que los eventos lleguen fuera del orden. Las condiciones de la red pueden provocar que los clics posteriores lleguen antes que los anteriores. Utilice el campo de fecha y hora para ordenar los eventos correctamente.
Disseny para la fiabilidad:
- Acepta eventos rápidamente y procesa de forma asincrónica
- Haga que las operaciones de la base de datos sean idempotentes (es seguro repetirlas)
- Incorpore redundancia en su punto final
- Supervise los eventos omitidos
- Para casos de uso críticos, verifique los datos de los webhooks con sondeos periódicos de la API
Patrón de procesamiento asíncrono
No procese los eventos de forma sincrónica en su controlador de webhooks. Acepta el evento, ponlo en cola, devuelve el éxito inmediatamente y procésalo en segundo plano:
# Python with queue-based processing
from flask import Flask, request, jsonify
import queue
import threading
app = Flask(__name__)
event_queue = queue.Queue()
@app.route('/webhook', methods=['POST'])
def webhook_handler():
# Validate secret key
if not validate_webhook(request):
return jsonify({'error': 'Unauthorized'}), 401
# Queue event immediately, don't process synchronously
event_data = request.get_json()
event_queue.put(event_data)
# Return success before processing
return jsonify({'status': 'received'}), 200
def process_events():
while True:
event = event_queue.get()
# Process event: save to database, call APIs, etc.
handle_event(event)
event_queue.task_done()
# Start background processor
processor = threading.Thread(target=process_events, daemon=True)
processor.start()
Esto permite que su terminal sea rápido (responde en menos de un segundo), lo que reduce el riesgo de que se agote el tiempo de espera y, al mismo tiempo, procesa los eventos de forma exhaustiva.
Mejores prácticas de seguridad
Valide siempre la clave secreta. Cuando creas un webhook en el panel de control de Rebrandly, generamos un secreto aleatorio. Lo enviamos al encabezado de apikey. Compruébalo en cada solicitud.
Formato de clave secreta: la clave secreta es un UUID estándar (identificador de 128 bits) con el formato de 8-4-4-4-12 caracteres hexadecimales (por ejemplo, 550e8400-e29b-41d4-a716-446655440000). Sigue el estándar UUID v4.
Si el secreto se pierde y un usuario usa el UUID en un sistema externo, tendrá que actualizarlo. Ten en cuenta que esta clave no es necesaria para llamar a los webhooks.
Almacene los secretos correctamente:
- Usa variables de entorno o un administrador de secretos
- Nunca envíe secretos al control de versiones
- Recita los secretos periódicamente
Trata los webhooks como cualquier API externa:
- Valide todos los datos antes de usarlos
- Desinfecte las entradas antes de las operaciones de la base de datos
- Límite tarifario para evitar el abuso
- Registrar los errores de autenticación para la supervisión de la seguridad
Rendimiento y límites
Rapidez de entrega: Los eventos suelen llegar entre unos segundos y un par de minutos después del clic. AWS administra el procesamiento por lotes directamente cuando almacenamos los clics; esto generará lotes o clics individuales en función del volumen.
Tasa de éxito: Mantenemos una tasa de envíos exitosos del 99,9% (Nota: esta medición no incluye los fallos en los terminales de los clientes, solo los envíos exitosos por parte de Rebrandly).
Sin límite de tarifas para los eventos: Tu punto final recibe los eventos tan rápido como los usuarios hacen clic en tus enlaces, desde tráfico ocasional hasta ráfagas de gran volumen durante las campañas principales. No hay límites establecidos en este momento. Los eventos están en cola por nuestra parte, por lo que su terminal los recibe tan rápido como puede procesarlos.
Límites de webhooks basados en planes (son límites de configuración, no de eventos):
- Profesional: 1 punto final de webhook
- Crecimiento: 5 puntos finales de webhook
- Empresarial: 100 puntos finales de webhook como máximo
Si alcanzas el límite de webhooks, puedes eliminar los webhooks antiguos que no necesites. Hay advertencias cuando te acercas al límite.
Diseña tu oyente de webhooks para gestionar los picos de tráfico. Usa el equilibrio de carga, el escalado automático y la agrupación de conexiones para las campañas con mucho tráfico.
Probando tu webhook
1. Configurar un punto final de prueba
Usa un servicio como webhook.site y crea una URL pública para las pruebas locales.
2. Crea el webhook en Rebrandly
Ve a Configuración de la cuenta > Webhooks:
- Nombre: «Webhook de prueba»
- URL: la URL de su punto final de prueba
- Secreto: copie el secreto generado en sus variables de entorno
- Espacio de trabajo: elige los enlaces del espacio de trabajo que activarán los eventos
3. Enviar un evento de prueba
Haz clic en «Enviar evento de prueba» en el panel de control de Rebrandly. Revise los registros de sus terminales para verificar:
- Llega el evento
- Pases de validación secretos
- La carga útil se analiza correctamente
Formato de evento de prueba: los eventos de prueba utilizan datos sintéticos pero coinciden con la estructura exacta de las cargas útiles de producción. No se rellenarán todos los parámetros; los eventos de prueba están diseñados para verificar la conectividad y la autenticación, no para representar los datos reales de los clics.
4. Activa un clic real
Haz clic en uno de los enlaces de tu marca. En 10 segundos, deberías recibir un webhook con datos de clics reales.
5. Escenarios de fallas en las pruebas
- Devuelve un error 500 desde tu punto final (el evento no se volverá a intentar)
- Tarda más de 30 segundos en responder (se agota el tiempo de espera de la solicitud)
- Devolver códigos de estado no válidos (la entrega del webhook falla)
Ejemplos de integración
Transmite clics a BigQuery
from google.cloud import bigquery
from flask import Flask, request, jsonify
app = Flask(__name__)
client = bigquery.Client()
table_id = "project.dataset.clicks"
@app.route('/webhook', methods=['POST'])
def webhook_handler():
if not validate_webhook(request):
return jsonify({'error': 'Unauthorized'}), 401
event_data = request.get_json()
rows = []
for event in event_data['data']:
rows.append({
'timestamp': event['timestamp'],
'slashtag': event['route']['slashtag'],
'country': event['client']['geo']['country'],
'city': event['client']['geo']['city'],
'device': event['client']['agent']['device']['name'],
'destination': event['route']['destination']['raw']
})
# Insert rows into BigQuery
errors = client.insert_rows_json(table_id, rows)
if errors:
print(f"Errors: {errors}")
return jsonify({'status': 'error'}), 500
return jsonify({'status': 'received'}), 200
Active el flujo de trabajo de HubSpot
const express = require('express');
const axios = require('axios');
app.post('/webhook', async (req, res) => {
if (!validateWebhook(req)) {
return res.status(401).json({ error: 'Unauthorized' });
}
const eventData = req.body;
for (const event of eventData.data) {
// Update contact in HubSpot based on link clicked
const linkClicked = event.route.slashtag;
if (linkClicked === 'pricing') {
await axios.post('https://api.hubapi.com/contacts/v1/contact/email/{email}/profile', {
properties: [
{
property: 'viewed_pricing',
value: 'true'
},
{
property: 'last_pricing_view',
value: event.timestamp
}
]
}, {
headers: { 'Authorization': `Bearer ${process.env.HUBSPOT_API_KEY}` }
});
}
}
res.status(200).json({ status: 'received' });
});
Enviar eventos a Google Analytics 4
import requests
def send_to_ga4(event):
# GA4 Measurement Protocol
ga4_endpoint = f"https://www.google-analytics.com/mp/collect?measurement_id={GA4_MEASUREMENT_ID}&api_secret={GA4_API_SECRET}"
payload = {
'client_id': event['key'],
'events': [{
'name': 'link_click',
'params': {
'slashtag': event['route']['slashtag'],
'destination': event['route']['destination']['raw'],
'country': event['client']['geo']['country'],
'city': event['client']['geo']['city'],
'device': event['client']['agent']['device']['name']
}
}]
}
response = requests.post(ga4_endpoint, json=payload)
return response.status_code == 204
@app.route('/webhook', methods=['POST'])
def webhook_handler():
if not validate_webhook(request):
return jsonify({'error': 'Unauthorized'}), 401
event_data = request.get_json()
for event in event_data['data']:
send_to_ga4(event)
return jsonify({'status': 'received'}), 200
Publica notificaciones en Slack
app.post('/webhook', async (req, res) => {
if (!validateWebhook(req)) {
return res.status(401).json({ error: 'Unauthorized' });
}
const eventData = req.body;
for (const event of eventData.data) {
// Alert team when specific links get clicked
const linkClicked = event.route.slashtag;
const location = `${event.client.geo.city}, ${event.client.geo.country}`;
if (linkClicked === 'product-demo') {
await axios.post(process.env.SLACK_WEBHOOK_URL, {
text: `🎯 Product demo link clicked!\nLocation: ${location}\nTime: ${event.timestamp}`
});
}
}
res.status(200).json({ status: 'received' });
});
Solución de problemas
Problema: Los eventos no llegan
Comprobar:
- ¿Se puede acceder a su terminal desde Internet público? (Postman Test con curl)
- ¿Estás devolviendo los códigos de estado 200-299?
- ¿Su terminal responde en 30 segundos?
- ¿Creaste el webhook en el espacio de trabajo correcto?
Problema: error de autenticación
Comprobar:
- ¿La clave secreta se almacena correctamente en las variables de entorno?
- ¿Estás leyendo correctamente el encabezado de apikey? (Los nombres de los encabezados no distinguen entre mayúsculas y minúsculas, pero pueden necesitar minúsculas en algunos marcos)
- ¿Copiaste el secreto completo del panel de control de Rebrandly?
Problema: los eventos llegan fuera del orden
Esto es lo que se espera. Utilice el campo de marca de tiempo para ordenar los eventos correctamente. Haga que las operaciones de la base de datos sean idempotentes para que procesar el mismo evento dos veces no cause problemas.
Problema: Faltan eventos durante el tiempo de inactividad
No volvemos a intentar las entregas fallidas. Si tu terminal no funcionaba, esos eventos se perderán. Opciones:
- Cree redundancia en su punto final (varios servidores, comprobaciones de estado)
- Supervisa las tasas de entrega de los webhooks y alerta sobre las caídas
- Para casos de uso críticos, compara los datos de los webhooks con los datos de la aplicación. El período de retención de los clics más antiguos es de 30 días.
Problema: errores de tiempo de espera
Su terminal tarda más de 30 segundos en responder. Solución:
- Acepta el evento instantáneo y devuelve 200
- Poner en cola el evento para su procesamiento asincrónico
- No realices llamadas sincrónicas a la API ni consultas largas a bases de datos en tu controlador de webhooks
PREGUNTAS MÁS FRECUENTES
¿Puedo filtrar los eventos que recibo?
Aún no. Los webhooks envían todos los eventos de clic desde el espacio de trabajo configurado. Filtra por tu parte en función de la barra diagonal, la URL de destino u otros campos de carga útiles.
¿Qué tipos de eventos se admiten?
Simplemente haz clic en eventos ahora mismo. Estamos estudiando la creación de enlaces, las actualizaciones de enlaces y los eventos relacionados con las actividades en el espacio de trabajo para futuras versiones.
¿Puedo usar el mismo punto final para varios espacios de trabajo?
Sí, pero tendrás que crear una configuración de webhook independiente para cada espacio de trabajo. Usa el campo clave de la carga útil para identificar qué webhook envió el evento.
¿Los webhooks funcionan con códigos QR?
Sí. Los escaneos de códigos QR activan los mismos eventos de clic que los clics en los enlaces directos.
¿Vuelven a intentar los eventos si mi punto final falla?
No. No volvemos a intentar los eventos. Cada uno se envía una vez. Diseñe su terminal para que sea confiable.
¿Puedo ver el historial de envíos?
Sí. En el panel de control de Rebrandly, abre los detalles de tu webhook para ver los intentos de entrega recientes, las tasas de éxito y los códigos de respuesta. Se almacenan los últimos 30 días del historial.
Qué puedes construir
Análisis en tiempo real: Transmite los eventos de clics directamente a Google Analytics 4, Segment o a su almacén de datos. Compara el rendimiento de la campaña con otras métricas sin cambiar de plataforma.
Flujos de trabajo automáticos: Activa secuencias de correo electrónico cuando los clientes potenciales hacen clic en las páginas de precios. Actualice las puntuaciones de clientes potenciales en su CRM en función de la participación en el contenido. Envía notificaciones a Slack cuando las campañas alcancen el límite de tráfico.
Lógica empresarial personalizada: Dirija los datos de clics a herramientas internas, active flujos de trabajo complejos de varios pasos o combine eventos de clics con otras fuentes de datos para crear modelos de atribución personalizados.
Los webhooks automatizan el flujo de datos que antes requería exportaciones manuales. En comparación con las exportaciones por lotes, los webhooks reducen la entrada manual de datos en un 95%. En comparación con las encuestas, los webhooks entregan los eventos a medida que ocurren: menos llamadas a la API, sin demoras y menores costos de infraestructura.
Cómo llegar
- Crear un webhook en Rebrandly: Ve a Configuración de la cuenta > Webhooks
- Configure su terminal usando uno de los ejemplos de código anteriores
- Almacene la clave secreta en sus variables de entorno
- Pruébalo con el botón «Enviar evento de prueba»
- Despliegue y empieza a recibir eventos de clics reales
Comience de forma sencilla: cree un punto final que registre los eventos. A continuación, añada la lógica empresarial que necesita: almacenamiento de bases de datos, llamadas a la API y activadores del flujo de trabajo.
¿Preguntas? Ponte en contacto con el soporte de Rebrandly o visite nuestro Documentación de API.
