Passer au contenu principal
Les webhooks permettent à AgencyHandy de transmettre des données à vos systèmes externes dès qu’un changement survient — sans interrogation périodique (polling). Lorsqu’un événement configuré se déclenche (par exemple, une commande est mise à jour ou un ticket est créé), AgencyHandy envoie une requête HTTP POST avec une charge utile (payload) JSON à l’URL du point de terminaison que vous spécifiez. Cela facilite la synchronisation en temps réel d’outils externes comme les CRM, les systèmes de facturation ou les tableaux de bord personnalisés avec votre espace de travail AgencyHandy.
Les espaces de travail du forfait Business Pro prennent en charge jusqu’à 30 000 événements de webhook par période de facturation. Vérifiez les limites de votre forfait avant de configurer des automatisations à volume élevé.

​
Événements pris en charge

Vous pouvez abonner un webhook à n’importe quelle combinaison des événements suivants :
CatégorieÉvénements
ServiceCreated, Updated, Deleted
OrderCreated, Updated, Deleted
TaskCreated, Assigned, Completed, Updated
InvoiceStatus changed
Client / UserNew client added, Client/user deleted
ProposalSent, Received, Accepted, Rejected
TicketCreated, Assigned, Status changed
PaymentReceived, Failed
Service PackageCreated, Updated, Deleted

​
Créer un webhook

1

Accéder à Webhook Management

Dans la barre latérale gauche, accédez à Integrations → Webhooks Management.
2

Authentifier votre jeton

Cliquez sur le bouton Management pour authentifier votre jeton de webhook. Ce jeton est utilisé pour signer les charges utiles sortantes afin que vous puissiez vérifier qu’elles proviennent bien d’AgencyHandy.
3

Créer un nouveau webhook

Cliquez sur Create New Webhook pour ouvrir le formulaire de configuration du webhook.
4

Saisir l'URL du point de terminaison

Dans le champ Endpoint URL, saisissez l’URL du système externe qui doit recevoir les données du webhook. Il doit s’agir d’un point de terminaison POST accessible publiquement.
5

Sélectionner le type de contenu

Choisissez JSON comme type de contenu. AgencyHandy envoie toutes les charges utiles de webhook au format application/json.
6

Sélectionner les événements du webhook

Choisissez chaque événement qui doit déclencher ce webhook. Vous pouvez sélectionner des événements de plusieurs catégories — par exemple, Order: Created et Invoice: Status changed peuvent tous deux pointer vers le même point de terminaison.
7

Activer le webhook

Activez le bouton radio Active. Lorsqu’il est actif, AgencyHandy transmet les charges utiles de tous les événements sélectionnés à votre point de terminaison en temps réel.
8

Enregistrer la configuration

Vérifiez vos paramètres, puis cliquez sur Save. Le webhook apparaît dans la liste et commence à transmettre les événements immédiatement.

​
Tester un webhook

Après avoir créé un webhook, envoyez une charge utile de test pour confirmer que votre point de terminaison est joignable et traite correctement les données.
1

Ouvrir le webhook

Dans la liste Webhooks Management, cliquez sur le webhook que vous souhaitez tester.
2

Cliquer sur Test Event

Cliquez sur le bouton Test Event sur la page de détail du webhook.
3

Sélectionner un événement de test

Choisissez un exemple d’événement dans la liste des événements configurés sur ce webhook (par exemple, Order: Created).
4

Envoyer la charge utile de test

Cliquez sur Send. AgencyHandy publie un exemple de charge utile vers l’URL de votre point de terminaison.
5

Vérifier le résultat

Vérifiez dans votre système externe que la charge utile de test est bien arrivée et a été traitée comme prévu. De retour dans AgencyHandy, cliquez sur le webhook pour consulter son historique — vous pouvez voir la requête complète, la réponse renvoyée par votre point de terminaison et redélivrer tout événement passé si nécessaire.
Utilisez un outil comme Webhook.site ou RequestBin comme point de terminaison temporaire lors de la configuration afin d’inspecter la forme exacte de la charge utile avant de connecter votre système réel.

​
Authentifier les charges utiles de webhook

Chaque requête de webhook sortante d’AgencyHandy inclut un en-tête de signature que votre point de terminaison peut utiliser pour vérifier que la charge utile est authentique et n’a pas été altérée.

​
En-tête de signature

x-ah-sig: <signature>
AgencyHandy ajoute cet en-tête à chaque requête de webhook. Extrayez la valeur des requêtes entrantes et transmettez-la au point de terminaison de vérification.

​
Vérifier une signature de webhook

Envoyez la requête suivante pour confirmer qu’une charge utile est authentique : 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
requis
L’ID du webhook qui a reçu l’événement. Vous le trouverez sur la page de détail du webhook dans AgencyHandy.
​
signature
string
requis
La valeur de l’en-tête x-ah-sig provenant de la requête de webhook entrante.
​
secret
string
requis
Le secret du webhook affiché sur la page de détail du webhook dans AgencyHandy.
​
payload
object
requis
Le corps JSON brut reçu de la requête de webhook d’AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Réponses
​
verification_status
string
SUCCESS lorsque la signature est valide. FAILED lorsque la vérification échoue (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Gardez votre secret de webhook confidentiel. Renouvelez-le périodiquement et mettez à jour votre logique de vérification immédiatement après le renouvellement. Ne l’exposez jamais dans du code côté client ni dans des dépôts publics.

​
Notes importantes

  • L’URL de votre point de terminaison doit être une URL POST HTTPS accessible publiquement.
  • Si votre point de terminaison est temporairement indisponible, consultez le panneau d’historique du webhook dans AgencyHandy — vous pouvez redélivrer tout événement passé directement depuis cet endroit.
  • Surveillez régulièrement l’activité des webhooks pour détecter les livraisons échouées ou les tentatives d’accès non autorisées.
  • Les webhooks qui échouent de manière répétée peuvent être mis en pause par AgencyHandy — examinez les journaux de livraison pour détecter les problèmes à temps.