Webhooks : s'abonner aux événements de liens et de clics

Les webhooks poussent des événements d'Elido vers votre serveur au fur et à mesure qu'ils se produisent. Utilisez-les plutôt que de sonder l'API quand vous avez besoin de données en temps réel — les cas d'usage typiques incluent la synchronisation des métadonnées de liens avec votre CRM, la construction d'un tableau de bord personnalisé ou le déclenchement d'un pipeline CI quand un lien est publié.

Ajouter un endpoint webhook#

Dashboard → Webhooks → Nouvel endpoint.
Collez l'URL vers laquelle nous devons faire des POST. Elle doit être HTTPS — nous rejetons le HTTP simple lors de la création.
Choisissez les types d'événements souhaités. La liste complète est ci-dessous.
(Optionnel) Collez un secret de signature, ou laissez-nous en générer un. Le secret est affiché une seule fois ; copiez-le avant de quitter la page.
Enregistrer. Nous envoyons immédiatement un événement test pour que vous puissiez confirmer que l'endpoint est accessible.

Catalogue d'événements#

Les types d'événements actuels. Les noms suivent <ressource>.<action> et restent stables d'une version à l'autre.

link.created — un nouveau lien court a été créé.
link.updated — la destination, le slug, l'expiration ou le mot de passe a changé.
link.deleted — le lien a été soft-supprimé (encore récupérable pendant 30 jours).
link.clicked.aggregated — toutes les 60 secondes, nous envoyons les compteurs de clics par lien pour la fenêtre précédente. Nous ne livrons pas d'événements par clic via les webhooks (le volume écraserait la plupart des endpoints) — utilisez l'export de clics pour les données d'événements brutes.
domain.verified — la vérification DNS d'un domaine personnalisé a réussi.
domain.tls_renewed — Caddy a renouvelé le certificat TLS pour un domaine personnalisé.
qr.generated — un SVG/PNG de code QR a été rendu.
abuse.flagged — notre scanner d'URL a marqué une destination comme suspecte.
member.invited / member.removed — changements d'appartenance au workspace.

Forme de la charge utile#

Chaque événement a la même enveloppe :

{
  "id": "evt_2c8L9N4M5",
  "type": "link.created",
  "created_at": "2026-05-15T09:42:11.382Z",
  "workspace_id": 4123,
  "data": {
    "link_id": 891234,
    "slug": "spring-2026",
    "destination": "https://acme.com/spring-sale",
    "created_by": "user_5821"
  }
}

id est unique par livraison. Utilisez-le pour l'idempotence — si vous recevez le même id deux fois (parce que nous avons retenté), ignorez le doublon.

Vérifier les signatures#

Nous signons chaque corps de webhook avec HMAC-SHA256 en utilisant le secret de votre endpoint. La signature se trouve dans l'en-tête Elido-Signature sous la forme t=<unix_ts>,v1=<hex>.

Pour vérifier en Node :

import { createHmac } from "node:crypto";

function verify(secret: string, body: string, header: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");
  return expected === parts.v1;
}

Nous incluons le timestamp dans la charge utile signée pour prévenir les replays. Rejetez les événements où |maintenant - t| > 300 secondes.

Tentatives#

Nous réessayons les livraisons échouées (toute réponse non-2xx, ou aucune réponse dans les 10 secondes) avec un backoff exponentiel : 30s, 1m, 5m, 30m, 2h, 12h. Après 6 échecs, nous marquons l'endpoint comme en échec et arrêtons de réessayer cet événement spécifique. L'endpoint reste abonné ; les nouveaux événements continuent à tenter la livraison.

L'endpoint reste en échec pour 5 livraisons consécutives → nous le désactivons automatiquement et envoyons un email au propriétaire du workspace. Réactivez-le dans le tableau de bord une fois que vous avez corrigé votre serveur.

Journal de livraison#

Ouvrez n'importe quel webhook dans le tableau de bord pour voir les 500 dernières livraisons, avec le code de statut, le temps de réponse et le corps de requête/réponse pour chacune. Les livraisons échouées peuvent être rejouées manuellement depuis cette vue.

Tests locaux#

Utilisez la CLI Elido pour transférer les webhooks vers localhost :

npx @elido/cli webhooks forward --url http://localhost:3000/webhooks

La CLI enregistre un endpoint temporaire qui dure jusqu'à votre Ctrl-C, tunnelise les livraisons vers votre machine et affiche le corps de la requête pour chaque événement.

Limites#

20 endpoints par workspace (Pro), 100 (Business).
Taille maximale de charge utile signée de 10 Ko. Les charges utiles plus grandes sont divisées — data inclut un flag truncated: true et une URL pour récupérer le corps complet.
50 événements par seconde soutenus par endpoint. Les rafales sont mises en file d'attente.

Résolution des problèmes#

L'endpoint signale 401 dans le journal de livraison. Votre endpoint vérifie les signatures avec le mauvais secret. Comparez le secret dans Webhooks → Endpoint → Paramètres avec celui que votre serveur a stocké.

Certains événements arrivent deux fois. Soit nous avons retenté après une réponse lente, soit votre endpoint a expiré sans répondre. Utilisez l'id de l'événement pour l'idempotence.

Les compteurs link.clicked.aggregated ne correspondent pas au tableau de bord analytique. Le tableau de bord est en temps réel (dans les 30s d'un clic) ; le webhook est fenêtré à 60s. Il y a aussi une petite (~1%) divergence car les bots filtrés du tableau de bord sont encore inclus dans les agrégats bruts jusqu'à la fermeture de la fenêtre de filtre de bots.