Le test d'une API tierce commence souvent par le proxy : l'itinéraire sortant se configure vite, sans se poser de questions. Puis le webhook du même fournisseur arrive — un rappel indiquant qu'une commande est payée, qu'un numéro a reçu un SMS ou qu'une tâche est terminée — et les données n'arrivent tout simplement pas. Voyons pourquoi le proxy n'y est pour rien, d'où vient la rupture et comment organiser la réception des rappels pour qu'elle ne dépende pas du canal sortant.

Le proxy modifie l'itinéraire sortant, il n'ouvre pas l'entrée

Le serveur proxy se place entre votre client et l'API distante uniquement sur le trajet sortant : c'est vous qui initiez la connexion, et il remplace l'adresse de retour ainsi que l'IP sous laquelle la requête est vue. Tout ce qui suit n'est qu'une réponse à une connexion que vous avez déjà ouverte. Le webhook fonctionne à l'inverse : l'initiateur, c'est le fournisseur, pas vous. Il ouvre une nouvelle connexion vers l'URL que vous avez enregistrée à l'avance dans l'espace client ou dans les paramètres de la requête, et cette connexion n'a aucun lien avec le canal que vous avez utilisé peu avant pour appeler son API.

D'où une confusion fréquente : on change de canal sortant et l'on pense que les rappels suivront désormais un autre chemin. En réalité, l'itinéraire d'une requête entrante dépend uniquement de l'endroit où pointe l'URL du récepteur et de la visibilité de cette adresse depuis l'extérieur, et non du moyen par lequel partent vos requêtes sortantes.

Pourquoi le rappel n'arrive pas

Un webhook perdu a peu de causes possibles, et toutes se situent du côté du récepteur, pas de l'émetteur. La machine se trouve derrière le NAT d'un routeur domestique ou de bureau sans port redirigé : vu de l'extérieur, son adresse n'existe tout simplement pas. L'adresse locale de développement n'est pas résolue depuis Internet, par définition. L'URL enregistrée pointe vers un hôte interne, visible uniquement depuis le réseau de l'entreprise. Le certificat TLS est expiré ou délivré pour un autre domaine, et la négociation s'interrompt avant la transmission du corps de la requête. Le serveur répond avec un code autre que 2xx : la plupart des fournisseurs cessent de renvoyer l'événement après plusieurs échecs.

Autre cause à part : la liste d'autorisation (allowlist) chez le fournisseur lui-même. L'infrastructure a changé, l'entrée n'a pas été mise à jour, et les appels s'éteignent en silence, sans aucune erreur dans l'interface.

Comment recevoir correctement les rappels

Le récepteur de rappels doit être une adresse accessible publiquement, avec un port ouvert et un certificat TLS valide — un domaine ou une IP que le fournisseur peut joindre directement, sans proxy ni tunnel de votre côté. Cette exigence est indépendante du canal que vous utilisez pour les requêtes sortantes vers la même API.

La bonne architecture de réception sépare deux tâches : confirmer rapidement la réception et traiter les données sans se presser. En entrée, un gestionnaire léger enregistre le corps brut de la requête dans une file d'attente et répond aussitôt 200, sans attendre la logique métier. Le traitement se fait ensuite de façon asynchrone, depuis la file, dans un processus distinct. Cela protège des délais d'attente (timeouts) côté fournisseur : si le traitement utile prend plusieurs secondes alors que la limite de réponse n'est que de quelques fractions de seconde, un schéma synchrone finira tôt ou tard par perdre des événements à la moindre baisse de performance.

Si vous ne pouvez pas obtenir d'adresse publique — réseau fermé, banc d'essai, environnement temporaire sans domaine —, utilisez le polling plutôt que le push : la plupart de ces API proposent un point d'accès parallèle pour interroger le statut ou la liste des événements. Interrogez-le selon un calendrier. Le délai de réception de l'événement passera de quelques secondes à la durée de l'intervalle d'interrogation, mais l'exigence d'accessibilité publique disparaît complètement.

Vérifier la livraison

La vérification s'appuie sur deux journaux indépendants, et non sur un seul. Le premier est le journal de livraison dans l'espace client du fournisseur : on y voit les tentatives, les codes de réponse et les temps. Le second est le journal de votre propre récepteur : il atteste que la requête est bien parvenue jusqu'à votre code, et qu'elle n'a pas été interceptée par un répartiteur de charge ou un CDN qui a répondu 200 de lui-même, sans transmettre le corps plus loin. Un statut « livré » dans l'interface d'un tiers, sans trace correspondante dans votre file d'attente, signale une rupture quelque part au milieu du trajet, et non la preuve que l'intégration fonctionne.

Il faut aussi vérifier la signature : si le webhook est signé avec une clé HMAC et que le secret est périmé après une rotation, le serveur rejettera en silence des événements valides en les prenant pour des faux — vu de l'extérieur, cela ressemble à « rien n'arrive ».

Où le proxy reste malgré tout utile

Il reste utile sur le trajet sortant de ce même ensemble. Si vous êtes passé au polling plutôt qu'au push, chaque interrogation est une requête sortante vers l'API, et vous pouvez la répartir comme n'importe quel autre trafic vers un serveur tiers : par zone géographique, par fréquence, avec rotation d'adresse en cas de limite de débit. Autre scénario : vérifier ce que voit la plateforme elle-même depuis le pays voulu — si le rappel dépend d'une logique propre à une zone géographique chez le fournisseur, il est plus pratique de la tester depuis la bonne zone que depuis l'adresse d'un centre de données choisie par défaut.

Questions fréquentes

Peut-on recevoir des webhooks via un serveur proxy ?

Le fournisseur doit pouvoir joindre directement votre récepteur, et le canal que vous utilisez pour les requêtes sortantes ne participe pas à cette chaîne. Si vous devez masquer l'adresse réelle du serveur, on place devant lui un proxy inverse : c'est un autre rôle, à ne pas confondre avec le proxy sortant destiné aux requêtes du client vers l'API d'un tiers.

Pourquoi l'espace client du fournisseur indique-t-il « livré » alors que les données sont absentes ?

Le statut « livré » signifie que le fournisseur a reçu une réponse 2xx de votre adresse — or la réponse a pu venir d'un répartiteur de charge, d'un CDN ou d'un autre service sur le même domaine, sans transmettre le corps à la file d'attente. Comparez le journal du fournisseur avec celui de votre propre récepteur, et ne vous fiez pas uniquement au statut affiché dans l'interface d'un tiers.

Que faire si l'on ne peut pas obtenir d'adresse publique ?

Passez au polling : interrogez le point d'accès de statut selon un calendrier au lieu d'attendre une notification push. Le délai de réception de l'événement augmentera, mais l'exigence d'accessibilité publique de la machine disparaît complètement.

Pour la partie sortante de l'ensemble — interroger l'API du fournisseur ou vérifier la logique depuis le pays voulu —, un canal dédié ou à rotation du catalogue de proxys convient. La configuration est décrite dans l'article rotation d'IP par API, et les métriques du canal dans le contenu comment vérifier la qualité d'un proxy.