Webhooks

Un webhook est une adresse de votre serveur que Posty5 appelle quand quelque chose se produit. Au lieu d’interroger Posty5 sur les nouvelles visites, votre système est prévenu en quelques secondes, avec un événement JSON qu’il peut vérifier.

Note

Les webhooks dépendent de votre forfait. Les livraisons ne coûtent aucun crédit. Consultez la page des crédits pour plus de détails. Crédits des fonctionnalités

Créer un point de terminaison

1. Dans le tableau de bord Posty5, ouvrez Paramètres du compte et choisissez Webhooks.

2. Ajoutez un point de terminaison, saisissez son adresse HTTPS et choisissez les événements qu’il reçoit.

3. Choisissez tous vos liens et codes QR ou seulement certains, si les visites de bots comptent, et si les événements arrivent un par un ou par lots.

4. Enregistrez, puis copiez le secret de signature. Il n’est affiché qu’une seule fois.

5. Utilisez Envoyer un test pour vérifier que votre serveur reçoit et valide un événement webhook.test.

L’adresse doit utiliser HTTPS et être accessible depuis internet. Les adresses de réseaux privés et locaux sont refusées, et les redirections ne sont pas suivies. Vous pouvez avoir jusqu’à 10 points de terminaison.

Événements

Event
short_link.visited	Quelqu’un a ouvert l’un de vos liens courts, y compris via l’image QR du lien.
short_link.visits_milestone	Un lien court a atteint l’un des nombres de visites que vous avez définis (jusqu’à 10 valeurs).
qr_code.scanned	Quelqu’un a scanné l’un de vos codes QR dynamiques.
qr_code.scans_milestone	Un code QR a atteint l’un des nombres de scans que vous avez définis.
webhook.test	Envoyé uniquement quand vous utilisez Envoyer un test.

Les événements de visite et de scan ne sont pas encore envoyés

Aujourd’hui, Posty5 n’envoie que l’événement de test. Les événements de visite et de scan, et leurs paliers, commenceront à la sortie des statistiques de visites. Vous pouvez déjà créer et tester des points de terminaison, qui recevront alors ces événements sans aucun changement.

Les codes QR statiques n'envoient aucun événement

Un code QR statique contient directement son contenu, un scan n’atteint donc jamais Posty5 et aucun événement ne peut être envoyé. Seuls les codes QR dynamiques et les liens courts produisent des événements.

À quoi ressemble un événement

Chaque événement est un POST JSON avec un id, un type, la version de l’API, sa date de création et ses données, le lien ou le code QR et la visite.

{
  "id": "evt_6700f1c2a9e4b51d2c3f0a11",
  "type": "short_link.visited",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-04T12:00:00.000Z",
  "data": {
    "target": {
      "type": "shortLink",
      "id": "66f0c2a9e4b51d2c3f0a1122",
      "code": "aB3xY9",
      "url": "https://pst5.com/_aB3xY9",
      "name": "Spring sale",
      "destinationUrl": "https://shop.example/sale",
      "tag": "spring",
      "refId": null
    },
    "visit": {
      "at": "2026-10-04T11:59:59.120Z",
      "channel": "qr",
      "country": "EG",
      "deviceType": "mobile",
      "os": "Android",
      "browser": "Chrome",
      "referrerHost": null,
      "language": "ar",
      "isBot": false,
      "outcome": "redirect"
    }
  }
}

Les événements de palier contiennent data.milestone avec la métrique, la valeur atteinte et la date, sans visite.

Avec la livraison par lots, un POST de type batch contient jusqu’à 500 événements dans data.events.

Ce qui n’est jamais envoyé

Les événements ne contiennent jamais l’adresse IP du visiteur, le user agent complet, l’adresse de provenance complète, un identifiant du visiteur ni l’ID de votre compte. Les visites de bots sont exclues sauf si vous les incluez.

Vérifier la signature

Posty5 signe chaque livraison avec le secret de votre point de terminaison, selon la spécification Standard Webhooks, dans trois en-têtes. Rejetez toute requête dont la signature ne correspond pas ou dont l’horodatage date de plus de 5 minutes.

• webhook-id
• webhook-timestamp
• webhook-signature

En Node.js, utilisez le paquet @posty5/webhooks.

import { verifyWebhookSignature } from "@posty5/webhooks";

// rawBody is the request body exactly as received, before JSON parsing.
const event = verifyWebhookSignature({
  payload: rawBody,
  headers: request.headers,
  secret: process.env.POSTY5_WEBHOOK_SECRET,
});

En .NET, utilisez le paquet Posty5.Webhooks.

using Posty5.Webhooks;

var webhookEvent = WebhookSignature.Verify(rawBody, headers, secret);

Dans tout autre langage, n’importe quelle bibliothèque Standard Webhooks vérifie les événements Posty5 avec votre secret.

Attention

Vérifiez le corps exactement tel qu’il a été reçu. Analyser le JSON puis le resérialiser modifie les octets et casse la signature.

Nouvelles tentatives et échecs

• Répondez avec un statut 2xx sous 10 secondes. Toute autre réponse compte comme un échec.
• Une livraison échouée est retentée après 30 secondes, 2 minutes, 10 minutes, 1 heure, 6 heures et 24 heures, puis abandonnée.
• Chaque nouvelle tentative porte le même webhook-id, pour que votre serveur puisse ignorer un événement déjà traité.
• Un point de terminaison est désactivé après 20 livraisons échouées d’affilée sur au moins 24 heures, ou immédiatement s’il répond 410 Gone. Vous recevez une notification et pouvez le réactiver depuis le tableau de bord.
• La liste des livraisons du point de terminaison affiche chaque tentative avec son statut et la réponse de votre serveur, et permet de renvoyer une livraison.

Renouveler le secret

Si le secret a pu fuiter, renouvelez-le depuis le menu du point de terminaison. Pendant 24 heures, les livraisons portent deux signatures, une par secret, pour mettre à jour votre serveur sans manquer d’événements.

Sans code, dans n8n

Le nœud Posty5 Trigger crée et vérifie le point de terminaison pour vous. n8n Posty5 Trigger