Les équipes marketing et d'ingénierie gèrent les données de clics cloisonnées. Les rapports arrivent avec des heures de retard. Les exportations manuelles introduisent des erreurs. Les décisions sont prises sur la base d'informations périmées.
Les webhooks Rebrandly fournissent des données sur les événements de clic à vos systèmes dans les 10 secondes suivant chaque interaction. Mise à jour des analyses en temps réel. Les automatisations se déclenchent lorsque l'intention de l'utilisateur est active. Les équipes peuvent accéder au contexte complet de la campagne sans avoir à se connecter à plusieurs plateformes.
By Sondages Report: au lieu de vérifier à plusieurs reprises les nouveaux clics, les webhooks transmettent les événements au fur et à mesure qu'ils se produisent ; moins d'appels d'API, pas de délais d'interrogation, des coûts d'infrastructure réduits.
Par rapport aux exportations par lots: les exportations manuelles impliquent de ne pas oublier d'extraire les données, de convertir les formats de fichiers et de les télécharger vers les systèmes de destination. Les Webhooks automatisent ce flux de travail, réduisant ainsi la saisie manuelle des données de 95 %.
Ce guide couvre les modèles de mise en œuvre, de sécurité et d'intégration pour les développeurs qui créent des flux de travail automatisés avec l'infrastructure Webhook de Rebrandly.
La charge utile du webhook
Chaque fois que quelqu'un clique sur le lien de votre marque, Rebrandly envoie un HTTP POST à votre terminal avec cette charge utile JSON :
DATA :
[
{
« horodatage » : « 25-010-2025 T 02:36:47.132 Z »,
« client » : {
« agent » : {
« navigateur » : {
« nom » : « chrome-mobile »,
« version » : « 121.0.0.0 »
},
« Oui » : {
« nom » : « Android »,
« version » : « android-10"
},
« device » : {
« nom » : « smartphone »
}
},
« géo » : {
« pays » : « États-Unis »,
« région » : « CA »,
« ville » : « San Francisco »
}
},
« itinéraire » : {
« identifiant » : « 12345abcde »,
« slashtag » : « product lancement »,
« Créé à » : « 2023-08-31T 04:13:48.385 »,
« domaine » : {
« identifiant » : « 8f104cc5b6ee4a4ba7897b06ac2ddcfb »,
« raw » : « brand.link »,
« zone » : « lien.marque »
},
« destination » : {
« brut » : « https://example.com/landing-page »,
« protocol » : « https »,
« hostname » : « exemple.com »,
« chemin » : « /landing page »
}
}
}
],
clé : « userID_32f5164718384fcda6503f550295885e-configid_db2a7cdeb91f4a2b9"
Demand heads:
- Type de contenu : application/json
- X-Rebrandly-Secret : your_secret_key (pour l'authentification)
Que contient la charge utile:
- horodatage : horodatage ISO 8601 UTC. Utilisez-le pour ordonner les événements s'ils arrivent dans l'ordre.
- client.agent : navigateur, système d'exploitation, type d'appareil. Idéal pour les analyses et la détection des robots.
- client.geo - Pays, région, ville. À utiliser pour l'analyse géographique ou la localisation.
- client.location - Données géographiques avec les codes de pays au format ISO 3166-1 A-2 (par exemple, « nous », « it »). Les codes de région utilisent le format ISO 3166-1 alpha-2. L'emplacement est déterminé par l'adresse IP.
- route : ID du lien, barre oblique (la moitié arrière de votre lien court), domaine, URL de destination. Connecte les clics à des campagnes spécifiques.
- key - Identifiant unique au format `RB-Clicks-Stream-1-yyyy-MM-DD-HH-MM-SS- (GUID) `. Cela est plus utile pour que Rebrandly trouve rapidement le clic si nécessaire.
Base-work
Voici un point de terminaison de webhook minimal qui valide le secret et stocke les événements :
# Exemple Python/Flask
depuis flask import Flask, request, jsonify
import system
app = Flacon (__nom__)
@app .route ('/webhook', methods= ['POST'])
def webhook_handler () :
N° 1. Validez la clé secrète
expected_secret = os.environ.get (« API key »)
received_secret = request.headers.get (« clé API »)
est expected_secret ! = secret_reçu :
return jsonify ({'error' : 'Unauthorized'}), 401
N° 2. Obtenez la charge utile
event_data = request.get_json ()
N° 3. Traitez-le (stockez, transférez, déclenchez des flux de travail)
for a event in event_data ['data'] :
print (« Cliquez sur {event ['timestamp']} »)
print (« Flink : {event ['route'] ['slashtag']} »)
print (« Lieu : {événement ['client'] ['géo'] ['ville']} »)
# Enregistrer dans la base de données, appeler d'autres API, etc.
N° 4. Renvoyer le succès rapidement (dans les 30 secondes)
return jsonify ({'status' : 'received'}), 200
si __name__ == '__main__' :
app.run (port = 5000)
//Example Node.js/Express
const express = require (« express ») ;
application const = express () ;
app.use (express.json ()) ;
app.post ('/webhook', (requis, res) => {
//1. Validez la clé secrète
const ExpectedSecret = Process.env.Rebrandly_Secret_Key ;
const ReceivedSecret = req.headers ['apikey'] ;
oui (ExpectedSecret ! == Secret reçu) {
return res.status (401) .json ({error : 'Unauthorized'}) ;
}
//2. Obtenez la charge utile
const EventData = req.body ;
//3. Traite-le
EventData.Data.ForEach (event => {
console.log (`Cliquez sur $ {event.timestamp} `) ;
console.log (`Lien : $ {event.route.slashtag} `) ;
console.log (`Emplacement : $ {event.client.geo.city} `) ;
//Enregistrer dans la base de données, appeler d'autres API, etc.
}) ;
//4. Rendez le succès rapidement
res.status (200) .json ({status : 'received'}) ;
}) ;
app.listen (5000, () => {
console.log (« Webhook écouteur exécuté sur le port 5000 ») ;
}) ;
Vos exigences en matière de terminaux:
- Accepter les requêtes HTTP POST
- Validez l'en-tête apikey
- Répondez dans les 5 secondes (renvoyez 200 à 299 codes d'état en cas de succès)
- Soyez accessible via HTTPS
- Gère les frais utiles JSON
Critic Fiability Information
Nous ne réessayons pas les livraisons ayant échoué. Chaque événement est envoyé une seule fois. Si votre terminal est en panne ou renvoie une erreur, cet événement est terminé.
Les événements peuvent arriver dans le désordre. Les conditions du réseau peuvent faire en sorte que les clics suivants arrivent avant les précédents. Utilisez le champ d'horodatage pour organiser correctement les événements.
Conception axée sur la fiabilité:
- Acceptez rapidement les événements, traitez-les de manière asynchrone
- Rendre les opérations de base de données idempotentes (possibilité de les répéter en toute sécurité)
- Intégrez la redondance à votre terminal
- Surveillez les événements manqués
- Pour les cas d'utilisation critiques, recoupez les données du webhook avec un sondage périodique de l'API
Asynchrone treatment model
Ne traitez pas les événements de manière synchrone dans votre gestionnaire de webhook. Acceptez l'événement, mettez-le en file d'attente, renvoyez immédiatement le résultat, puis procédez en arrière-plan :
# Python avec traitement basé sur les fichiers d'attente
depuis flask import Flask, request, jsonify
fichier d'importation
import de fils
app = Flacon (__nom__)
event_queue = Queue.queue ()
@app .route ('/webhook', methods= ['POST'])
def webhook_handler () :
# Valider la clé secrète
si ce n'est pas validate_webhook (requête) :
return jsonify ({'error' : 'Unauthorized'}), 401
# Mettez immédiatement l'événement en file d'attente, ne le traitez pas de manière synchrone
event_data = request.get_json ()
event_queue.put (données_events)
# Réussite du retour avant le traitement
return jsonify ({'status' : 'received'}), 200
def process_events () :
alors que c'est vrai :
event = event_queue.get ()
# Evénement du processus : enregistrer dans la base de données, appeler des API, etc.
handle_event (event)
event_queue.task_done ()
# Démarre le processeur d'arrière-plan
processeur = Threading.Thread (target=process_events, daemon=True)
processeur.start ()
Cela permet à votre terminal de rester rapide (il répond en moins d'une seconde), réduisant ainsi le risque de temporisation tout en continuant à traiter les événements de manière approfondie.
Bonnes pratiques en matière de sécurité
Validez toujours la clé secrète. Lorsque vous créez un webhook dans le tableau de bord Rebrandly, nous générons un secret aléatoire. Nous l'envoyons dans l'en-tête apikey. Vérifiez-le à chaque demande.
Format de clé secrète : votre clé secrète est un UUID standard (identifiant 128 bits) au format 8-4-4-4-12 caractères hexadécimaux (par exemple, 550e8400-e29b-41d4-a716-446655440000). Cela correspond à la norme UUID v4.
Si le secret est modifié et qu'un utilisateur utilise l'UUID dans un système externe, il devra le mettre à jour. Notez que cette clé n'est pas requise pour appeler des webhooks.
Stockez correctement les secrets:
- Utilisez des variables d'environnement ou un gestionnaire de secrets
- Ne confiez jamais de secrets au contrôle de version
- Faites pivoter les secrets périodiquement
Traitez les webhooks comme n'importe quelle API externe:
- Validez toutes les données avant de les utiliser
- Nettoyez les entrées avant les opérations de base de données
- Limite tarifaire pour prévenir les abus
- Enregistrer les échecs d'authentification pour la surveillance de la sécurité
Performances et limites
Delivery speed : Les événements arrivent généralement quelques secondes à quelques minutes après le clic. Le traitement par lots est géré directement par AWS lorsque nous stockons les clics. Il déclenche des lots ou des clics uniques en fonction du volume.
Rate of Succedent : Nous maintenons un taux d'envoi réussi de 99,9 % (Remarque : cette mesure n'inclut pas les défaillances des terminaux des clients, seuls les envois réussis du côté de Rebrandly).
Aucune limite tarifaire pour les événements : Votre terminal reçoit les événements dès que les internautes cliquent sur vos liens, qu'il s'agit de trafic occasionnel ou de pics de volume lors de campagnes majeures. Aucune limite n'est fixée pour le moment. Les événements sont mis en file d'attente de notre côté, de sorte que votre terminal les reçoit le plus rapidement possible.
Limites de webhook basées sur un forfait (il s'agit de limites de configuration, pas de limites d'événements) :
- Professional: 1 point de terminaison Webhook
- Croissance: 5 points de terminaison du webhook
- L'entreprise: 100 points de terminaison Webhook au maximum
Si vous atteignez la limite de webhooks, vous pouvez supprimer les anciens webhooks dont vous n'avez pas besoin. Des avertissements sont émis lorsque vous approchez de la limite.
Concevez votre écouteur Webhook pour gérer les photos de trafic. Utilisez l'équilibrage de charge, la mise à l'échelle automatique et le regroupement de connexions pour les campagnes à fort trafic.
Testez votre webhook
1. Configurer un point de terminaison de test
Utilisez un service tel que webhook.site pour créer une URL publique pour les tests locaux.
2. Creez le webhook dans Rebrandly
Accédez à Paramètres du compte > Webhooks :
- Nom : « Test Webhook »
- URL : Your Point of Test Terminaison URL
- Secret : copiez le secret généré dans vos variables d'environnement
- Espace de travail : choisissez les liens de l'espace de travail qui déclencheront des événements
3. Send a test event
Click on « Envoyer un événement test » in the board Rebrandly board. Consultez les journaux de vos terminaux pour vérifier :
- L'événement arrive
- Passeports de validation secrets
- La charge utile est correctement analysée
Format des événements de test : les événements de test utilisent des données synthétiques mais correspondent à la structure exacte des charges utiles de production. Tous les paramètres ne seront pas renseignés. Les événements de test sont conçus pour vérifier la connectivité et l'authentification, et non pour représenter les données de clics réelles.
4. Déclenchez un véritable clic
Click on the one of your brand links. Dans les 10 secondes, vous devriez recevoir un webhook contenant des données de clics réelles.
5. Scénarios d'échec des tests
- Renvoie une erreur 500 depuis votre terminal (l'événement ne sera pas réessayé)
- Délai de réponse supérieur à 30 secondes (délai d'expiration de la demande)
- Retrait des codes de statut non valides (échec de la livraison du webhook)
Examples of integration
Diffusez des clics vers BigQuery
depuis google.cloud import bigquery
depuis flask import Flask, request, jsonify
app = Flacon (__nom__)
client = BigQuery.client ()
table_id = « projet.dataset.clicks »
@app .route ('/webhook', methods= ['POST'])
def webhook_handler () :
si ce n'est pas validate_webhook (requête) :
return jsonify ({'error' : 'Unauthorized'}), 401
event_data = request.get_json ()
lines = []
for a event in event_data ['data'] :
lignes.add ({
'timestamp' : event ['timestamp'],
'slashtag' : event ['route'] ['slashtag'],
« pays » : event ['client'] ['géo'] ['pays'],
« ville » : event ['client'] ['geo'] ['ville'],
« appareil » : event ['client'] ['agent'] ['appareil'] ['nom'],
« destination » : event ['itinéraire'] ['destination'] ['brut']
})
# Insérer des lignes dans BigQuery
errors = client.insert_rows_json (table_id, lines)
en cas d'erreur :
print (« Errors : {errors} »)
return jsonify ({'status' : 'error'}), 500
return jsonify ({'status' : 'received'}), 200
Débloque le flux de travail Hu
const express = require (« express ») ;
const axios = require (« axios ») ;
app.post ('/webhook', async (requis, res) => {
oui (! Webhook validé (requis) {
return res.status (401) .json ({error : 'Unauthorized'}) ;
}
const EventData = req.body ;
for (event const de EventData.data) {
//Mise à jour du contact dans HubSpot en fonction du lien cliqué
const LinkClicked = event.route.slashtag ;
if (LinkClicked === « tarification ») {
attendez axios.post ('https://api.hubapi.com/contacts/v1/contact/email/{email}/profile', {
propriétés : [
{
property : 'Viewed_pricing',
value : « true »
},
{
property : « last_pricing_view »,
valeur : event.timestamp
}
]
}, {
en-têtes : {'Autorisation' : `Porteur $ {process.env.Hubspot_API_KEY} `}
}) ;
}
}
res.status (200) .json ({status : 'received'}) ;
}) ;
Send events to Google Analytics 4
imports requests
def send_to_ga4 (event) :
# GA4 Measure Protocol
ga4_endpoint = f » https://www.google-analytics.com/mp/collect?measurement_id={GA4_MEASUREMENT_ID}&api_secret={GA4_API_SECRET} »
charge utile = {
'client_id' : event ['key'],
« events » : [{
« nom » : « clique_lien »,
« paramètres » : {
'slashtag' : event ['route'] ['slashtag'],
« destination » : event ['route'] ['destination'] ['brut'],
« pays » : event ['client'] ['géo'] ['pays'],
« ville » : event ['client'] ['geo'] ['ville'],
« appareil » : event ['client'] ['agent'] ['appareil'] ['nom']
}
}]
}
response = requests.post (ga4_endpoint, json=charge utile)
renvoie la réponse.status_code == 204
@app .route ('/webhook', methods= ['POST'])
def webhook_handler () :
si ce n'est pas validate_webhook (requête) :
return jsonify ({'error' : 'Unauthorized'}), 401
event_data = request.get_json ()
for a event in event_data ['data'] :
send_to_ga4 (event)
return jsonify ({'status' : 'received'}), 200
Publier des notifications sur Slack
app.post ('/webhook', async (requis, res) => {
oui (! Webhook validé (requis) {
return res.status (401) .json ({error : 'Unauthorized'}) ;
}
const EventData = req.body ;
for (event const de EventData.data) {
//Alerter l'équipe lorsque des liens spécifiques sont cliqués
const LinkClicked = event.route.slashtag ;
const location = `$ {event.client.geo.city}, $ {event.client.geo.country} `;
if (LinkClicked === « démonstration du produit ») {
attendez axios.post (process.env.Slack_WebHook_URL), {
text : `🎯 Le lien de démonstration du produit a été cliqué ! \nLieu : $ {location}\nHeure : $ {event.timestamp} `
}) ;
}
}
res.status (200) .json ({status : 'received'}) ;
}) ;
Resolution of problems
Problème : les événements n'arrivent pas
Vérifiez :
- Votre terminal est-il accessible depuis l'Internet public ? (Testez avec curl or Postman)
- Vous avez 200 à 299 codes d'état ?
- Votre terminal répond-il dans les 30 secondes ?
- As-tu créé le webhook dans le bon espace de travail ?
Problème : échec de l'authentification
Vérifiez :
- La clé secrète est-elle correctement stockée dans vos variables d'environnement ?
- Lisez-vous correctement l'en-tête apikey ? (Les noms d'en-tête ne font pas la distinction entre majuscules et minuscules mais peuvent exiger des minuscules dans certains frameworks)
- As-tu copié le secret complet depuis le tableau de bord Rebrandly ?
Problème : les événements arrivent dans le désordre
C'est ce qui est attendu. Utilisez le champ d'horodatage pour trier correctement les événements. Rendez les opérations de votre base de données idempotentes afin que le fait de traiter deux fois le même événement ne pose pas de problèmes.
Problème : événements manquants pendant les temps d'arrêt
Nous ne réessayons pas les livraisons ayant échoué. Si votre terminal était en panne, ces événements sont perdus. Possibilités :
- Intégrez la redondance à votre terminal (serveurs multiples, bilans de santé)
- Surveillez le taux de livraison des webhooks et alertez en cas de baisse
- Pour les cas d'utilisation critiques, recoupez les données du webhook avec les données de l'application. La durée de conservation des anciens clics est de 30 jours.
Problème : erreurs de temporisation
Your terminal met plus de 30 secondes to answer. Solution :
- Acceptez l'événement immédiatement et renvoyez 200
- Mettre l'événement en file d'attente pour le traitement asynchrone
- N'effectuez pas d'appels d'API synchronisés ni de longues requêtes de base de données dans votre gestionnaire Webhook
FAQ
Puis-je filtrer les événements que je reçois ?
Pas encore Les webhooks envoient tous les événements de clic depuis l'espace de travail configuré. Filtrez de votre côté en fonction de la barre oblique, de l'URL de destination ou d'autres champs de charge utiles.
Quels types d'événements sont pris en charge ?
Cliquez simplement sur les événements dès maintenant. Nous explorons la création de liens, les mises à jour de liens et les événements liés aux activités de l'espace de travail pour les prochaines versions.
Puis-je utiliser le même terminal pour plusieurs espaces de travail ?
Oui, mais vous devez créer une configuration de webhook distincte pour chaque espace de travail. Utilisez le champ clé de la charge utile pour identifier quel webhook a envoyé l'événement.
Les webhooks fonctionnent-ils avec les codes QR ?
Oui Les scans de codes QR déclenchent les mêmes événements de clic que les clics directs sur les liens.
Les événements sont-ils réessayés en cas de défaillance de mon terminal ?
Non. Nous ne réessayons pas les événements. Chacun est envoyé une seule fois. Concevez votre terminal dans un souci de fiabilité.
Puis-je consulter l'historique des livraisons ?
Oui Dans le tableau de bord Rebrandly, ouvrez les détails de votre webhook pour voir les récentes tentatives de livraison, les taux de réussite et les codes de réponse. Les 30 derniers jours d'historique sont enregistrés.
Ce que vous pouvez construire
Analyses en temps réel: diffusez les événements liés aux clics directement dans Google Analytics 4, Segment ou votre entrepôt de données. Consultez les performances des campagnes et d'autres indicateurs sans changer de plateforme.
Automatised work flow: déclenchez des séquences d'e-mails lorsque les prospects cliquent sur des pages de tarification. Mettez à jour les scores des prospects dans votre CRM en fonction de l'engagement dans le contenu. Envoie des notifications Slack lorsque les campagnes atteignent des seuils de trafic.
Logique métier personnalisée: acheminez les données relatives aux clics vers des outils internes, déclenchez des flux de travail complexes en plusieurs étapes ou combinez des événements liés aux clics avec d'autres sources de données pour des modèles d'attribution personnalisés.
Les Webhooks automatisent le flux de données qui nécessitaient auparavant des exportations manuelles. Par rapport aux exportations par lots, les webhooks ont réduit la saisie manuelle des données de 95 %. Par rapport aux sondages, les webhooks transmettent les événements au fur et à mesure qu'ils se produisent : moins d'appels d'API, pas de retards, moins de coûts d'infrastructure.
Pour commencer
- Création d'un webhook in Rebrandly : allez dans Paramètres du compte > Webhooks
- Configurez votre terminal en utilisant l'un des exemples de code ci-dessus
- Stockez la clé secrète in your environment variables
- Testetez-le to the help of the button « Send a test event »
- Déployer and commencez à recevoir de vrais événements de clic
Commencez simplement : créez un point de terminaison qui enregistre les événements. Ajoutez ensuite la logique métier dont vous avez besoin : stockage de base de données, appels d'API, déclencheurs de flux de travail.
Est-ce que des questions ? Contactez le support Rebrandly or consulte our Documentation de l'API.
