Qu’est-ce qu’un webhook ?
Un webhook vous permet d’être notifié lorsque certaines actions système se produisent via un appel à une URL que vous fournissez. Les webhooks sont également connus sous le nom de « URL Callbacks » ou « HTTP push calls ». Votre URL doit utiliser SSL et commencer par HTTPS.Actions des webhooks
Voir les actions disponibles pour les webhooks.
Comprendre les webhooks Ayrshare
Les webhooks sont catégorisés par l’action spécifique et sont enregistrés au niveau du Primary Profile ou du User Profile. Toute mise à jour pour les Primary Profiles ou User Profiles est envoyée en premier au webhook enregistré pour le User Profile. Si le User Profile n’a pas de webhook enregistré, la mise à jour sera envoyée au webhook enregistré du Primary Profile. Par exemple :- Si un User Profile a un webhook Social Action enregistré et délie TikTok, l’URL du webhook Social Action enregistré pour le User Profile sera appelée. Le webhook du Primary Profile ne sera pas appelé.
- Si un User Profile délie TikTok et n’a pas de webhook Social Action enregistré, mais que le Primary Profile a bien un webhook enregistré, l’URL du webhook Social Action enregistré pour le Primary Profile sera appelée.
Enregistrer un webhook
Enregistrez un webhook en fournissant une URL de point de terminaison et le type d’action au point de terminaison POST/hook/webhook. Lorsque l’action se produit, un message HTTP POST sera envoyé à l’URL fournie.
Par exemple, enregistrez une URL pour être notifié du statut d’une publication programmée.
L’URL du point de terminaison du webhook ne doit pas utiliser de redirections et doit être l’URL de destination finale.
Si vous n’enregistrez que le webhook du Primary Profile, les User Profiles hériteront automatiquement du webhook du Primary Profile.
Pour avoir un webhook unique pour chaque User Profile, vous devez enregistrer un webhook pour chaque User Profile.
Après que votre webhook a reçu le
HTTP POST, votre serveur doit répondre avec
un statut HTTP 200 pour marquer l’appel comme réussi. Si votre serveur ne
répond pas dans les 15 secondes, la tentative est enregistrée comme un échec et
réessayée. Répondez dès que vous recevez la requête et effectuez votre traitement
de manière asynchrone. Un dépassement de délai n’est pas un rejet, donc si votre gestionnaire termine
le travail mais répond en retard, la nouvelle tentative vous fera le traiter deux fois.Nouvelles tentatives de webhook
Le fait qu’une livraison échouée soit réessayée dépend de la manière dont elle a échoué. Chaque nouvelle tentative porte le mêmehookId. La charge utile est reconstruite à chaque tentative, donc timeStamp — et la signature qui le couvre — peuvent différer.
Réessayé — échecs transitoires. Une réponse 429, 408 ou 425, tout 5xx, un délai dépassé ou une connexion interrompue fait l’objet de 9 tentatives d’envoi au maximum sur environ une heure — le premier envoi plus 8 nouvelles tentatives. Si l’échec persiste, la livraison est tentée à nouveau selon un calendrier décroissant — environ 5 minutes, 30 minutes, 2 heures et 12 heures plus tard. Une livraison peut donc arriver jusqu’à environ 16 heures après l’événement d’origine.
Non réessayé — rejets. Toute autre réponse 4xx, comme 400, 401, 403, 404 ou 410, est considérée comme définitive dès la première tentative. Elle indique que la requête elle-même a été rejetée, et la répéter ne changera pas le résultat.
Sémantique de livraison et idempotence
Ayrshare livre les webhooks au moins une fois. Les doublons occasionnels sont un fonctionnement normal, pas un défaut. Chaque consommateur doit traiter l’idempotence comme une propriété permanente. Les doublons se présentent sous deux formes différentes, et chacune nécessite une clé différente :hookId identifie une livraison d’un événement. Il est identique sur chaque nouvelle tentative de cette livraison, donc s’appuyer dessus rend les nouvelles tentatives sûres. Mais une nouvelle notification du même événement sous-jacent arrive avec un nouveau hookId, donc hookId seul ne permettra pas de reconnaître ce cas.
Modèle de récepteur recommandé :
- Répondez d’abord. Retournez
2xximmédiatement, puis traitez de manière asynchrone. Un dépassement de délai n’est pas un rejet. Si vous terminez le travail mais répondez en retard, l’événement est renvoyé. - Revendiquez
hookIdde manière atomique dès que la requête arrive : une contrainte d’unicité, unINSERT ... ON CONFLICT DO NOTHING, ou unSET NX. Pas une vérification lecture-puis-écriture. Deux tentatives peuvent arriver simultanément, et une protection de type vérifier-puis-agir laisse passer les deux. - Revendiquez également votre propre clé, construite à partir de la charge utile, afin qu’une deuxième notification portant un nouveau
hookIdsoit tout de même reconnue. Surmessages,idcombiné avecsubActionfonctionne bien. - Ensuite effectuez le travail, en conservant les deux revendications suffisamment longtemps pour couvrir la fenêtre de nouvelles tentatives et toute nouvelle notification ultérieure. Comme une nouvelle tentative peut arriver jusqu’à environ 16 heures plus tard, conservez vos revendications au moins 24 heures. Une revendication qui expire plus tôt ne reconnaîtra pas une tentative tardive, et vous traiterez deux fois le même événement.
L’
id de la charge utile n’est pas unique à lui seul pour chaque type d’événement. Le même
id de message se répète à travers les modifications et les réactions, et les charges utiles messageRead ne portent
aucun id. Combinez-le donc avec subAction plutôt que de l’utiliser seul.En-têtes de métadonnées de livraison
Chaque livraison porte deux en-têtes identifiant cette transmission spécifique, afin que vous puissiez distinguer un original d’une nouvelle tentative :X-Ayrshare-Delivery-Attempt est 0 lors du premier envoi et s’incrémente de un à chaque nouvelle tentative, donc toute valeur supérieure à 0 signifie que nous avons déjà envoyé cette livraison au moins une fois. Traitez-le comme un compteur non borné plutôt que comme un ensemble fixe de valeurs. Le nombre de nouvelles tentatives est un détail opérationnel qui peut changer. X-Ayrshare-Delivery-Id est unique à chaque tentative. Citez-le au support et il identifie l’enregistrement de livraison exact.
Ceux-ci identifient la transmission ; hookId identifie l’événement. Déduplifiez sur hookId, pas sur l’id de livraison. L’id de livraison est différent à chaque tentative par conception, donc rien ne serait jamais reconnu comme un doublon.
Sécurité des webhooks
Vous pouvez choisir d’ajouter une sécurité supplémentaire en configurant l’authentification HMAC en tant que requête HTTP. Cela est souvent fait pour empêcher les attaques par rejeu. Ayrshare utilise HMAC-SHA256 pour hacher le corps du message et l’inclut ainsi que l’horodatage UNIX dans l’en-tête du POST.X-Authorization-Content-SHA256 avec le HMAC-SHA256 du corps du POST. Le secret de signature est à l’échelle du profil : un secret par User Profile, utilisé pour toutes les actions de webhook de ce profil, si bien que le définir pour une action le modifie pour toutes les actions de ce profil. Les comptes multi-profils gèrent un secret distinct par profil (ciblez un profil avec l’en-tête Profile-Key).