Migrer de Bitly sans casser les liens : un playbook des modes de défaillance

Ana Kowalska est solutions engineer chez Elido qui a accompagné une douzaine de projets de migration jusqu'au basculement Bitly. Elle pense que la plupart de la douleur est évitable si vous auditez avant de bouger plutôt qu'après.

Le migrate-from-bitly-playbook couvre l'arc stratégique : auditer ce que vous avez, l'exporter, l'importer, basculer le DNS. Cet article est le bon point de départ si vous n'avez jamais fait de migration Bitly auparavant.

Cet article est différent. Il se concentre sur ce qui casse - les modes de défaillance spécifiques qui émergent une fois le plan conceptuel terminé et que vous exécutez réellement la migration contre des données de production. Sept d'entre eux reviennent à plusieurs reprises, et les sept sont évitables si vous savez quoi chercher.

TL;DR#

Les slugs Bitly sont sensibles à la casse ; de nombreuses plateformes de redirection ne le sont pas. bit.ly/AbCd et bit.ly/abcd sont des liens différents dans Bitly et se comporteront différemment si votre script de migration met les slugs en minuscules à l'import.
Les écarts de TTL DNS provoquent un écart de redirection même après le basculement du CNAME. Faites passer le TTL à 60 secondes au moins 24 heures avant le basculement, pas cinq minutes avant.
Les webhooks pointant vers les endpoints api-ssl.bitly.com cessent de se déclencher dès que vous annulez ou désactivez le compte Bitly. Recâblez chaque consommateur en aval avant de toucher au statut du compte.
Les deeplinks avec des segments de chemin (bit.ly/app/account/settings) entrent en collision avec toutes les règles de routage Elido qui correspondent aussi à un préfixe de chemin. Auditez les slugs deeplink séparément des slugs de redirection standard.

Les sept choses qui cassent vraiment#

Avant toute discussion sur l'outillage, il est utile d'avoir la taxonomie des défaillances devant soi. La plupart des post-mortems de migration pointent vers l'un de ces points :

1. Sensibilité à la casse du slug. Bitly préserve la casse dans les slugs - bit.ly/SummerSale et bit.ly/summersale sont des liens distincts. Si votre script d'import normalise les slugs en minuscules (un défaut courant dans les bibliothèques de gestion d'URL), vous créez silencieusement le mauvais slug et la variante avec lettre capitale renvoie 404. Cela affecte les campagnes email où le slug a été intégré en casse mixte.

2. Comportement de la barre oblique finale. bit.ly/campaign/ et bit.ly/campaign sont traités comme le même lien dans le routeur de Bitly. Certaines plateformes traitent la variante avec barre oblique finale comme un chemin distinct. Si votre espace de travail Elido est fronté par un reverse proxy avec normalisation d'URL stricte activée, une requête avec barre oblique finale peut se résoudre différemment du slug canonique.

3. Préservation de la chaîne de requête. Si l'URL de destination d'un lien Bitly contient déjà des paramètres de requête - https://acme.example/landing?source=bitly - et que le clic porte aussi des paramètres UTM ajoutés au moment du partage, vous devez vérifier que la fusion de destination se comporte de manière identique dans Elido. Le comportement par défaut de Bitly pour les UTM ajoutés est de les fusionner dans la chaîne de requête existante. Testez cela explicitement pour tout lien dont l'URL de destination porte déjà des paramètres.

4. Ajout d'UTM au niveau plateforme. Le palier entreprise de Bitly prend en charge l'ajout d'UTM au niveau de l'espace de travail : chaque redirection sortante reçoit un UTM ajouté indépendamment de ce que contient l'URL de destination d'origine. Si vous aviez cela activé dans Bitly et ne l'avez pas documenté, vous pouvez avoir une analytique dépendant d'UTM qu'Elido n'ajoute pas encore. Vérifiez vos paramètres d'espace de travail dans Bitly pour les règles d'auto-ajout avant d'exporter. L'équivalent Elido est les templates UTM au niveau de l'espace de travail ou de la campagne - la page fonctionnalité domaines personnalisés couvre où cette configuration vit.

5. Écart de TTL DNS. C'est la cause la plus fréquente d'un écart de redirection au basculement. Les résolveurs DNS mettent en cache l'ancien CNAME pendant la durée du TTL actuel. Si votre TTL est à 86400 secondes depuis deux ans, le changer à 300 secondes cinq minutes avant de basculer l'enregistrement A signifie que la plupart des résolveurs détiennent encore l'ancien enregistrement pendant 23 heures et 55 minutes supplémentaires. Le basculement n'est pas instantané ; il se propage.

6. Recâblage des webhooks. Tout système consommant des événements de webhook Bitly - pipelines analytiques, jobs d'enrichissement CRM, attribution de commandes Shopify - se déclenche contre l'URL d'endpoint Bitly. Cet endpoint s'éteint quand vous annulez ou rétrogradez le compte Bitly sous le palier qui prend en charge les webhooks. La configuration des webhooks Bitly vit au niveau du compte et n'est pas exportée avec les données de lien. Chaque consommateur doit être inventorié et repointé manuellement.

7. Collisions de chemin deeplink. Les deeplinks mobiles utilisent souvent le chemin de l'URL courte pour encoder l'état de navigation de l'app - bit.ly/app/profile/edit peut se mapper à une destination comme yourapp://profile/edit. Lorsque vous migrez ces slugs vers Elido, le slug app/profile/edit contient des barres obliques. Le routeur Elido peut traiter les chemins délimités par des barres obliques différemment du traitement opaque des slugs de Bitly. Vérifiez que les slugs deeplink avec des segments de chemin sont créés avec la chaîne de slug exacte, pas réinterprétés comme des chemins imbriqués.

Audit de pré-migration : segmenter par palier de risque#

L'API Bitly (consultée le 12/05/2026) expose les comptes de clics par lien via GET /v4/bitlink/{bitlink}/clicks/summary. Avant d'exporter et d'importer quoi que ce soit, utilisez-la pour segmenter votre inventaire.

La segmentation pratique :

Palier à ne-doit-pas-casser (top 1 %) : liens avec ≥10× le compte de clics médian sur les 30 derniers jours. Ce sont les liens en service dans les emails, supports imprimés, landing pages d'annonces payantes. Ils ont besoin d'une vérification manuelle après basculement, pas seulement de contrôles automatisés.
Palier à surveiller (9 % suivants) : liens avec volume de clics supérieur à la médiane. La vérification 301 automatisée est suffisante, mais signalez ceux qui se résolvent de manière inattendue.
Palier en masse (90 % restants) : slugs à faible trafic ou zéro clic. Vérifiez programmatiquement ; acceptez un petit taux d'erreur et corrigez sur signalement.

Exportez un résumé de clics de 30 jours par lien lors de l'étape d'inventaire. Une boucle de pagination directe contre la référence API Bitly (consultée le 12/05/2026) vous donne ces données ; le champ link_clicks dans l'endpoint group bitlinks est le compteur à vie, qui est plus grossier mais suffisant pour le triage :

# Paginate all links in a Bitly group and write to JSONL
NEXT_URL="https://api-ssl.bitly.com/v4/groups/${GROUP_GUID}/bitlinks?size=100"
while [ -n "$NEXT_URL" ]; do
  RESP=$(curl -s -H "Authorization: Bearer ${BITLY_TOKEN}" "$NEXT_URL")
  echo "$RESP" | jq -c '.links[]' >> bitly-links.jsonl
  NEXT_URL=$(echo "$RESP" | jq -r '.pagination.next // empty')
done

Triez la sortie par link_clicks décroissant. Le top 1 % est votre palier à ne-doit-pas-casser. Exportez leurs slugs dans un fichier séparé avant d'exécuter l'import en masse.

Préservation du slug : l'appel d'import qui compte#

L'endpoint d'import en masse d'Elido à POST /v1/links/bulk accepte un champ slug par lien. Si vous ne le définissez pas explicitement, Elido génère un nouveau slug aléatoire - ce qui est le mauvais comportement pour une migration. Passez toujours le slug source.

# Bulk import with slug preservation - 100 links per call
curl -s -X POST "https://api.elido.app/v1/links/bulk" \
  -H "Authorization: Bearer ${ELIDO_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mig-batch-$(date +%s)" \
  -d '{
    "workspace_id": "'"${WORKSPACE_ID}"'",
    "domain_id": "'"${DOMAIN_ID}"'",
    "links": [
      {
        "slug": "SummerSale",
        "destination_url": "https://acme.example/summer",
        "tags": ["bitly-migrated", "campaign-summer"]
      },
      {
        "slug": "AbCd",
        "destination_url": "https://acme.example/landing",
        "tags": ["bitly-migrated"]
      }
    ]
  }'

Deux choses à noter dans cet appel. Premièrement, les valeurs de slug sont "SummerSale" et "AbCd" - casse mixte préservée exactement comme elle apparaissait dans Bitly. Ne les mettez pas en minuscules. Deuxièmement, l'en-tête Idempotency-Key signifie que vous pouvez relancer un batch partiel en toute sécurité ; Elido renvoie le lien existant plutôt que de créer un doublon. C'est le pattern correct pour une migration qui peut avoir besoin de reprendre.

Pour le palier à ne-doit-pas-casser, exécutez l'import interactivement par lien plutôt qu'en batch, et vérifiez chacun avant de procéder. Pour le palier en masse, batchez à 100 par appel et traitez le tableau d'erreurs dans la réponse pour attraper tous les slugs qui sont entrés en conflit ou ont échoué.

Basculement DNS sans écart#

Le basculement DNS est le moment où le trafic en direct se déplace. Bien fait, les utilisateurs ne subissent aucune interruption. Avec un TTL périmé, il y a un écart mesuré en heures, pas en minutes.

La séquence compte. Voir le diagramme de timeline ci-dessous.

Horizontal DNS cutover timeline showing T-7d TTL drop to 60s, T-0 A record flip, T+5min 95% propagation, T+1h TTL restore, T+24h audit pass

La timeline en détail :

T−7 jours : Faites passer le TTL sur le CNAME ou l'enregistrement A à 60 secondes. C'est l'étape critique que la plupart des équipes manquent. RFC 1034 §3.6 (IETF datatracker, section sur la mise en cache des enregistrements de ressources) définit le TTL comme la durée maximale de cache qu'un résolveur peut détenir l'enregistrement. Si votre TTL actuel est 86400 (un jour), le changer ne prend effet qu'après l'expiration de la version actuellement en cache. Vous devez abaisser le TTL au moins une période complète de TTL actuel avant le basculement. Une semaine est sûre ; 24 heures est le minimum.

T−1 heure : Vérifiez que le TTL bas s'est propagé. Utilisez un outil comme dig @8.8.8.8 links.yourbrand.com +ttl depuis au moins trois endpoints de résolveur différents. Le TTL rapporté devrait être proche de 60 secondes.

T−0 : Échangez la cible du CNAME du edge de Bitly vers celui d'Elido. Côté Elido, le domaine devrait déjà être enregistré et vérifié dans votre espace de travail - ne basculez pas le DNS avant que le edge d'Elido ne soit prêt à accepter le trafic. La première requête après propagation déclenche l'émission automatique de certificat TLS à la demande, qui se complète en environ 2-3 secondes sur cette seule requête. Les requêtes suivantes touchent le cache et se résolvent en quelques millisecondes à notre edge en région UE.

T+5 minutes : Lancez un spot-check depuis un deuxième réseau (utilisez un hotspot mobile pour contourner le cache de votre résolveur de bureau). curl -sI https://links.yourbrand.com/any-known-slug devrait renvoyer un 301 Moved Permanently pointant vers la destination attendue, provenant des en-têtes du edge d'Elido.

T+1 heure : Restaurez le TTL à sa valeur opérationnelle normale (300 ou 3600 secondes). Garder le TTL à 60 secondes indéfiniment ajoute de la charge à votre fournisseur DNS et à l'infrastructure de résolveur.

T+24 heures : Lancez l'audit complet des slugs (voir la section suivante).

Selon RFC 7231 §6.4.2, une réponse 301 Moved Permanently peut être mise en cache par des intermédiaires indéfiniment à moins qu'un en-tête de contrôle de cache explicite ne le remplace. Cela signifie que tout client qui a touché l'ancienne destination Bitly pendant l'écart de TTL peut avoir mis en cache un 301 pointant vers l'infrastructure de Bitly. Ces redirections en cache se résolvent correctement tant que l'infrastructure de Bitly est en service, ce qui est pourquoi la fenêtre de chevauchement de compte Bitly de 30 jours importe.

L'audit de chaîne 301 : vérification nocturne scriptée#

Après le basculement, lancez une boucle de vérification nocturne sur votre palier à ne-doit-pas-casser. Le but est d'attraper tout slug qui a changé de comportement - soit en renvoyant une destination inattendue, soit en renvoyant un 404, soit en développant une chaîne de redirection plus longue que deux sauts.

# Verify top slugs resolve correctly via Elido
# top-slugs.txt: one slug per line, no protocol prefix
DOMAIN="links.yourbrand.com"
FAIL=0

while IFS= read -r slug; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    --max-redirs 0 \
    "https://${DOMAIN}/${slug}")
  LOCATION=$(curl -s -I --max-redirs 0 \
    "https://${DOMAIN}/${slug}" \
    | grep -i '^location:' | tr -d '\r' | cut -d' ' -f2)

  if [ "$STATUS" != "301" ]; then
    echo "FAIL [$STATUS] $slug → expected 301"
    FAIL=$((FAIL + 1))
  else
    echo "OK  [301] $slug → $LOCATION"
  fi
done < top-slugs.txt

echo "---"
echo "Failures: $FAIL"
exit $FAIL

Lancez cela contre le palier à ne-doit-pas-casser (typiquement 50-200 slugs pour la plupart des équipes) chaque nuit pendant les deux premières semaines après basculement. Redirigez la sortie vers votre canal d'alerte. Si FAIL est non nul, vous voulez qu'un humain le regarde avant les pics de trafic matinaux.

Le drapeau --max-redirs 0 est intentionnel : vous voulez la redirection d'Elido, pas la destination finale. Si le Status est 200 au lieu de 301, quelque chose côté Elido sert la destination directement plutôt que de rediriger, ce qui signifie que le slug s'est résolu vers un lien configuré comme un pass-through direct. Cela vaut la peine d'enquêter.

Pour le palier à surveiller, lancez un scan hebdomadaire plus léger. Pour le palier en masse, fiez-vous aux rapports d'erreurs des systèmes en aval - les liens cassés dans les emails génèrent des changements de taux de rebond que votre plateforme email fera remonter.

Recâblage des webhooks#

Les webhooks Bitly sont documentés dans la référence API Bitly (consultée le 12/05/2026) sous la section Webhooks. Chaque webhook se déclenche sur les événements de clic et inclut les champs bitlink, référent et user-agent. Consommateurs courants :

Shopify : apps d'attribution qui suivent quel lien court a piloté une conversion. Configuré dans le panneau admin de l'app Shopify, pointant vers un endpoint tiers qui appelle la vérification de webhook Bitly.
Stripe : certains pipelines d'attribution de facturation taguent les inscriptions d'essai entrantes avec les données UTM du lien court d'origine, sourcées via le webhook Bitly.
Slack : bots de performance de liens qui postent des résumés de clics dans un canal #marketing.
Pipelines ETL personnalisés : tout pipeline de data warehouse qui ingère des événements de clic Bitly pour enrichissement ou jointures d'attribution.

La checklist de migration pour les webhooks :

Exportez votre configuration de webhook Bitly avant tout changement de compte. L'API Bitly GET /v4/workspaces/{workspace_guid}/webhooks renvoie la liste. Enregistrez-la dans un fichier.
Pour chaque consommateur, identifiez l'URL d'endpoint recevant les événements Bitly et le secret utilisé pour la vérification HMAC.
Configurez l'endpoint webhook Elido équivalent. Les payloads de webhook d'Elido ont un schéma différent de ceux de Bitly - les champs sont similaires mais pas identiques. Ajustez le handler du consommateur pour accepter le nouveau schéma.
Faites tourner les deux webhooks en parallèle pendant la fenêtre de chevauchement. Configurez Elido pour déclencher des webhooks à partir du jour du basculement, tout en gardant le webhook Bitly actif. Votre consommateur reçoit deux événements par clic pendant le chevauchement - dédupliquez sur l'URL courte + horodatage, ou acceptez le double comptage pendant la fenêtre de chevauchement comme un artefact connu.
Après 72 heures de livraison confirmée du webhook Elido, supprimez la configuration du webhook Bitly de chaque consommateur.

La fenêtre de grâce de rotation de secret est la période de chevauchement. Ne faites pas tourner le secret du webhook Elido jusqu'à ce que chaque consommateur ait été vérifié. Faire tourner le secret avant qu'un consommateur ne soit mis à jour signifie que ce consommateur abandonne silencieusement des événements sans erreur - la vérification HMAC échoue et la plupart des handlers de webhook rejettent les payloads à signature invalide sans alerter.

Plan de rollback : garder Bitly vivant pendant 30 jours#

La procédure de rollback est simple : remettez le CNAME DNS vers la cible Bitly. Parce que vous avez pré-staged la baisse de TTL et que l'enregistrement DNS est toujours à 60 secondes (jusqu'à ce que vous le restauriez), un rollback DNS se propage en moins de deux minutes.

Préparez la commande de rollback avant de commencer :

# Rollback script - run this to revert DNS to Bitly (adapt for your DNS provider)
# Route 53 example using AWS CLI
aws route53 change-resource-record-sets \
  --hosted-zone-id "${HOSTED_ZONE_ID}" \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "links.yourbrand.com",
        "Type": "CNAME",
        "TTL": 60,
        "ResourceRecords": [{"Value": "cname.bitly.com"}]
      }
    }]
  }'

Gardez ceci dans un fichier sur votre portable et dans un emplacement de runbook partagé avant le basculement. Le pire moment pour écrire des commandes d'infrastructure est pendant un incident actif.

Gardez le compte Bitly actif et sur un plan payant qui maintient la résolution des liens pendant 30 jours après basculement. Le migrate-from-bitly-playbook recommande 90 jours ; 30 est le minimum pratique pour les équipes qui doivent contrôler les coûts. Pendant la fenêtre de 30 jours, tout trafic qui se résout encore via Bitly (redirections en cache, vieux liens bit.ly dans des supports imprimés) continue de fonctionner. Après 30 jours, évaluez le trafic résiduel Bitly dans votre analytique et décidez si prolonger.

Ce qu'il faut surveiller pendant la fenêtre de 30 jours :

Le taux d'erreur d'Elido sur votre domaine personnalisé (surveillez les 404 inattendus dans le journal d'accès).
Tous les pics de trafic vers Bitly (le tableau de bord Bitly montre le trafic ; un pic peut signifier qu'une redirection en cache se résout encore via Bitly pour un slug à fort volume).
Taux d'erreur des consommateurs de webhook pour tous les consommateurs que vous avez recâblés.

Audit post-migration : ce qu'il faut journaliser#

Après la fenêtre de 30 jours, lancez un passage d'audit final. Ce qui appartient au journal d'audit :

Vérification	Méthode	Critère de réussite
Le compte de slugs correspond	`wc -l bitly-export.jsonl` vs compte API Elido	Dans les 1 % (tenir compte des liens archivés intentionnellement abandonnés)
Vérification 301 du palier à ne-doit-pas-casser	Script d'audit nocturne	Zéro échec pendant 7 jours consécutifs
Réconciliation du volume de clics	Comparer le total de clics Elido 30 jours vs le total Bitly 30 jours de la même période l'année dernière	Dans la variance saisonnière attendue
Confirmation des consommateurs de webhook	Vérifier que chaque consommateur reçoit les événements Elido et les traite correctement	Pas d'abandon silencieux pendant 7 jours
TTL DNS restauré	`dig +ttl links.yourbrand.com`	TTL à la valeur opérationnelle (300+ secondes)

Journalisez cela dans la table d'audit de votre équipe. Si votre espace de travail est sur un plan Business ou Entreprise, le journal d'audit d'Elido capture toutes les opérations API pendant l'import et est interrogeable via l'API. Tirez les enregistrements de batch d'import et stockez un instantané aux côtés de cette table.

Pièges courants : trois patterns du terrain#

La marque ecommerce DACH qui a perdu une semaine d'attribution email. Un détaillant en Allemagne a lancé une campagne newsletter utilisant des slugs Bitly avec des UTM par abonné ajoutés au moment de l'envoi. Le script de migration a normalisé tous les slugs en minuscules avant de les importer dans Elido. Après basculement, la plateforme email générait des liens avec les slugs originaux en casse mixte. Ces liens renvoyaient 404 depuis Elido parce que la casse du slug ne correspondait pas. Le correctif a été de relancer l'import avec des slugs avec casse préservée, mais à ce moment-là sept jours de trafic email avaient atterri sur des 404. L'attribution était irrécupérable pour cette cohorte. La leçon : testez un lien en direct de chaque canal actif avant de déclarer la migration complète.

La startup SaaS qui a triple-redirigé les utilisateurs mobiles. Une équipe growth avait un domaine personnalisé Bitly fronté par Cloudflare en mode proxy (nuage orange). Après basculement, les utilisateurs mobiles recevaient trois redirections : Cloudflare → edge Elido → destination. Le saut supplémentaire venait d'une Cloudflare Page Rule qui réécrivait HTTP en HTTPS avant de passer à Elido, puis Elido émettait son propre 301. iOS Safari mettait en cache la redirection intermédiaire Cloudflare comme redirection permanente pendant 30 jours. Le correctif a été de mettre l'enregistrement Cloudflare en nuage gris (DNS uniquement) et de supprimer la Page Rule conflictuelle. Les redirections en cache dans Safari ont mis 30 jours à expirer naturellement. Vérifiez le mode proxy de votre CDN avant le basculement, pas après.

L'agence qui a manqué un groupe Bitly. Une agence gérait trois marques clients sous un seul compte Bitly, chacune sous un groupe Bitly différent avec son propre domaine personnalisé. Le script de migration n'a interrogé que le groupe par défaut - celui sous lequel le token utilisateur de l'API a été créé. Deux domaines clients ont migré proprement. Le troisième, sous un groupe secondaire, n'a jamais été exporté. Après basculement, une campagne email de lancement de produit est partie pointant vers le domaine personnalisé non migré. Le domaine avait encore le CNAME de Bitly à TTL complet, et Bitly servait les liens correctement - mais la fenêtre de basculement pour ce domaine avait été déclarée terminée. La panique a été une re-migration complète dans les délais. La leçon : énumérez tous les groupes via GET /v4/user/groups avant de commencer toute étape d'export. Vérifiez que le token a accès à chaque groupe.

Où aller à partir d'ici#

Le migrate-from-bitly-playbook couvre la séquence stratégique complète pour les équipes qui démarrent à zéro sur la planification de migration. Cet article est le compagnon des modes de défaillance - utilisez-les ensemble.

Pour le côté produit de ce vers quoi vous migrez, la page solutions/marketeurs couvre les fonctionnalités d'attribution et de suivi de campagne auxquelles la plupart des projets de migration cherchent à accéder. La page /compare/vs-bitly est la référence de parité de fonctionnalités si vous confirmez encore que le changement en vaut la peine.

Si vous évaluez Elido aux côtés de Rebrandly ou Short.io, la comparaison elido-vs-bitly couvre les compromis tarifaires et de fonctionnalités à quatre volumes de trafic. La page fonctionnalité domaines personnalisés documente la vérification DNS et les mécaniques de provisionnement TLS en détail - à lire avant votre fenêtre de basculement DNS.

Les défaillances de migration sont presque toujours évitables. Le script d'audit, la discipline du TTL et l'inventaire des webhooks prennent deux heures de travail avant le basculement. Ils épargnent des jours de réponse aux incidents après.

Citations et sources

Bitly API Reference - dev.bitly.com/api-reference, accessed 2026-05-12
RFC 1034 - Domain Names: Concepts and Facilities, §3.6 (resource record caching) - datatracker.ietf.org/doc/html/rfc1034
RFC 7231 §6.4.2 - HTTP/1.1 Semantics and Content: 301 Moved Permanently - datatracker.ietf.org/doc/html/rfc7231#section-6.4.2
Bitly API - Groups and Bitlinks endpoints - dev.bitly.com/api-reference, accessed 2026-05-12

Essayer Elido

Collez une URL, obtenez un lien court

Sans inscription. Lien actif 30 jours. Inscrivez-vous pour le garder pour toujours.

Gratuit, sans inscription · 2 par jour