Configurer les webhooks pour une mise à jour automatique des statuts

Un webhook est un message qu’un système envoie à un autre lorsqu’il se passe quelque chose. Payload en envoie un à Salesforce lorsqu’un paiement est traité, refusé, remboursé, annulé ou rejeté, et lorsque de l’argent est déposé sur votre compte bancaire ou en est retiré. REDA Pay reçoit ces messages et met à jour la Pay Transaction correspondante, ou crée une Statement Activity pour un dépôt. Sans webhooks, un paiement accepté aujourd’hui et rejeté par la banque trois jours plus tard reste « processed » dans Salesforce jusqu’à ce que quelqu’un appuie à la main sur Sync Transaction.

La configuration comporte cinq parties : une adresse publique dans Salesforce que Payload peut joindre, l’accès de l’utilisateur invité derrière cette adresse, l’adresse sur le Pay Profile, l’accès de l’utilisateur Salesforce qui traite les messages, et le bouton Setup Webhooks qui enregistre l’adresse auprès de Payload.

Comment les éléments s’articulent

Payload ──(message webhook)──▶ votre site Salesforce public ──▶ REDA Pay ──▶ Pay Transaction mise à jour
                                 /services/apexrest/…            (traité par l’utilisateur Processus automatisé)

Payload a besoin d’une adresse qu’il peut appeler sans se connecter. Dans Salesforce, c’est un site : une adresse web publique appartenant à votre organisation, utilisée ici uniquement comme boîte aux lettres pour les messages de Payload. REDA Pay communique l’adresse complète à Payload ; vous ne fournissez que l’adresse de base du site.

Partie 1 — Créer le site public

Si votre organisation dispose déjà d’un site Salesforce utilisé pour des intégrations, vous pouvez le réutiliser ; passez à la partie 2. Sinon :

1. Ouvrez la Configuration, saisissez Sites dans la zone Recherche rapide et cliquez sur Sites (sous Interface utilisateur → Sites et domaines).
2. Si vous n’avez jamais créé de site, enregistrez d’abord un domaine : saisissez un nom dans la zone du domaine, cliquez sur Vérifier la disponibilité, acceptez les conditions et cliquez sur Enregistrer mon domaine de site Salesforce. Le domaine ressemble à yourcompany.my.salesforce-sites.com.
3. Cliquez sur Nouveau.
4. Renseignez : Étiquette du site (par exemple Payment Callbacks), Nom du site (rempli automatiquement), Adresse Web par défaut (un chemin court comme rpay, qui fera partie de l’adresse) et Page d’accueil du site actif : cliquez sur la recherche et choisissez n’importe quelle page, par exemple UnderConstruction. Personne ne visitera cette page.
5. Enregistrez, puis activez le site.

Notez l’adresse complète du site, telle qu’elle apparaît dans URL du site, par exemple https://yourcompany.my.salesforce-sites.com/rpay.

La page de détail du site de rappel des paiements (nommé REDA Payload dans cette organisation d’exemple) : Étiquette du site et Nom du site, Actif coché, Login Not Allowed, les pages d’accueil et le bouton Paramètres d’accès public

Un site utilisé uniquement pour les webhooks. Son URL du site est ce que vous saisissez sur le Pay Profile.

Partie 2 — Donner l’accès à l’utilisateur invité du site

Chaque site a un utilisateur invité, l’identité que Salesforce utilise pour les visiteurs non connectés. Les messages de Payload arrivent sous cette identité : elle doit donc être autorisée à exécuter la classe REDA Pay qui les reçoit.

1. Sur la page de détail du site, cliquez sur Paramètres d’accès public. Le profil de l’utilisateur invité s’ouvre.
2. Faites défiler jusqu’à Accès aux classes Apex activé (appelé Accès à la classe Apex dans l’interface de profil améliorée) et cliquez sur Modifier.
3. Déplacez rpay.PayloadCallback de la liste des classes disponibles vers celle des classes activées, puis cliquez sur Enregistrer. L’utilisateur invité n’a besoin de rien d’autre : cette classe se contente de transmettre le message à REDA Pay.

La section Accès à la classe Apex du profil de l’utilisateur invité du site (interface de profil améliorée), avec rpay.PayloadCallback

L’utilisateur invité a besoin exactement de cette classe. Elle reçoit le message de Payload et le transmet à REDA Pay.

Partie 3 — Saisir l’adresse du site sur le Pay Profile

1. Ouvrez l’application REDA Pay → Pay Profiles → votre profil → Modifier.
2. Dans Webhook API Base URL, collez l’adresse du site de la partie 1, avec https:// et le chemin, par exemple https://yourcompany.my.salesforce-sites.com/rpay.
3. Cliquez sur Enregistrer.

REDA Pay ajoute lui-même le reste de l’adresse. Vous ne saisissez jamais l’adresse complète du webhook.

Partie 4 — Donner l’accès à l’utilisateur Processus automatisé

Lorsqu’un message arrive, Salesforce le confie à un utilisateur système intégré appelé Processus automatisé (Automated Process), qui fait le travail : lire le message, trouver la Pay Transaction, demander à Payload son dernier statut et mettre à jour l’enregistrement. Cet utilisateur n’a aucun accès aux enregistrements REDA Pay tant que vous ne lui en donnez pas, et il n’apparaît pas dans la liste habituelle des utilisateurs : l’accès s’accorde donc avec un court script.

1. Ouvrez Configuration → Ensembles d’autorisations, ouvrez REDA Pay - Admin User et cliquez sur Cloner. Nommez la copie REDA Pay - Automated Process et enregistrez.
2. Copiez l’Id du clone depuis la barre d’adresse (la valeur de 18 caractères après /lightning/setup/PermSets/, ou les 15 caractères après id=).
3. Ouvrez la Developer Console (console du développeur) depuis le menu de l’engrenage ; si ce menu affiche Console Web à la place, ouvrez https://<votre My Domain>.my.salesforce.com/_ui/common/apex/debug/ApexCSIPage dans un nouvel onglet. Choisissez ensuite Debug → Open Execute Anonymous Window (la fenêtre d’exécution de code anonyme ; les menus de la Developer Console sont en anglais), collez la ligne ci-dessous avec votre Id et cliquez sur Execute :

insert new PermissionSetAssignment(
    AssigneeId = [SELECT Id FROM User WHERE Alias = 'autoproc' LIMIT 1].Id,
    PermissionSetId = '0PS000000000000AAA'   // l’Id de votre ensemble d’autorisations REDA Pay - Automated Process
);

La fenêtre signale la réussite. Si elle indique que l’attribution existe déjà, l’étape a déjà été faite.

Partie 5 — Enregistrer les webhooks auprès de Payload

1. Sur le Pay Profile, cliquez sur Setup Webhooks.
2. Lisez la boîte de dialogue : « System will delete all the existng webhooks and create new webhook setup. »
3. Cliquez sur Setup Webhooks. Attendez le message « Webhook setup created successfully. » et fermez la boîte de dialogue.
4. Ouvrez l’onglet Webhook Setup du profil. Il liste dix enregistrements Pay Profile Webhook, un par événement : payment, processed, authorized, credit, refund, reversal, void, decline, deposit et reject. Chacun affiche le Webhook Id attribué par Payload et le Webhook URL enregistré par REDA Pay. Le champ Webhook Setup Datetime [Payload] du profil est renseigné.

L’onglet Webhook Setup d’un Pay Profile listant dix Pay Profile Webhooks (payment, processed, authorized, credit, refund, reversal, void, decline, deposit, reject) avec leurs colonnes Webhook Id et Webhook URL

Dix webhooks, un par événement Payload. S’il en apparaît moins, l’enregistrement a échoué en cours de route : corrigez la cause et exécutez de nouveau Setup Webhooks.

Exécutez de nouveau Setup Webhooks chaque fois que vous modifiez le Webhook API Base URL ou remplacez la clé API.

Vérifier que cela fonctionne

Encaissez un petit paiement de test (consultez Encaisser un paiement) et ouvrez sa Pay Transaction. En quelques minutes, les champs Status, Status Code et Funding Status se mettent à jour sans que personne n’appuie sur Sync Transaction. Pour un paiement bancaire, le statut de financement passe de pending à batched lorsque Payload le regroupe en lot, et un dépôt sur votre compte bancaire crée ensuite une Statement Activity ; consultez Rapprocher les dépôts et les versements.

Si rien ne se met à jour, vérifiez dans cet ordre :

Ce que contiennent les messages

Un message indique seulement à REDA Pay quelle transaction a changé. REDA Pay demande ensuite à Payload l’état actuel de cette transaction et enregistre la réponse : l’enregistrement reflète donc toujours Payload, et non le message. Les messages qui concernent des transactions que Salesforce n’a jamais vues sont ignorés. Les messages de dépôt et de retrait créent ou actualisent une Statement Activity.

Erreurs à éviter

Questions fréquentes

Pour aller plus loin

• Comment les statuts de paiement restent à jour : ce que chaque événement fait aux enregistrements.
• Activer la récupération des paiements échoués : la tâche qui couvre les paiements dont le résultat n’a jamais été reçu.