Gérer des abonnements Webhook

La gestion des abonnements Webhook existants se fait au niveau de la catégorie "webhook-controller" des APIs ACTITO.

Grâce aux diverses opérations existantes, vous pourrez rechercher des abonnements Webhook, les modifier, les supprimer et obtenir le fichier d’erreurs pour une date en particulier.

images/download/attachments/615293560/image2019-4-4_10-52-0.png

Rechercher des abonnements

Il est possible de récupérer tous les abonnements à un Webhook pour une entité spécifique via l'opération GET/entity/{e}/webhookSubscription

Cette fonctionnalité vous permettra d'obtenir :

  • L'identifiant technique de l'abonnement au Webhook, qui doit être utilisé comme paramètre pour les opérations de mise à jour et de suppression d'un abonnement.

  • Les détails de la la définition de l'abonnementWebhook, c'est à dire la table, le type d'événement et les champs écoutés, ainsi que l'adresse sur laquelle les notifications d'événement vont être envoyées.

Le seul paramètre à renseigner est l'entité pour laquelle vous souhaitez obtenir les abonnement Webhook. Cependant, plusieurs options de filtres vous permettent de préciser votre sélection :

  • "tableType" : CUSTOM_TABLE ou PROFILE_TABLE

  • "tableId" : Il faut utiliser l'identifiant technique de la table, récupérable via l'interface ACTITO ou via Webservice

  • "eventType" : Ceci permet de trier les abonnements en fonction de leur type (CREATE, UPDATE, …)

  • "isActif" : Ce filtre permet de n’afficher que les Webhooks actifs

  • "webhookEndPointId" : Vous pouvez faire une recherche sur l'URL sur lesquels sont postés les événements

  • "page" et "pageSize" : Il s'agit de paramètres de pagination. La première page correspond à la page 0. "PageSize" indique le nombre d’abonnements affichés par page

  • "sort" et "sortDirection" : Ces paramètres vous permettent de trier les abonnements en fonction des paramètres présentés ci-dessus et de préciser si le tri est ascendant ou descendant.

Exemple de requête et du résultat obtenu : (Téléchargez cet exemple)

GET/entity/{e}/webhookSubscription
Curl call
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/webhookSubscription?page=0&pageSize=100"
 
Response body
[
{
"id": 13,
"entityId": 1,
"isActive": true,
"onTableType": "PROFILE_TABLE",
"onTableId": "46",
"onFields": [
"emailAdress",
"lastName",
"sex"
],
"eventType": "CREATE",
"targetUrl": "https://webhook.site/02de06e1-7e36-4d83-a516-f244c9ae503e"
},
{
"id": 14,
"entityId": 1,
"isActive": true,
"onTableType": "CUSTOM_TABLE",
"onTableId": "a459faa0-f57a-4947-8293-7f766bb7c797",
"onFields": [
"ticketId",
"montant"
],
"eventType": "CREATE",
"targetUrl": "https://webhook.site/b8fc552a-d469-4461-84d0-a360cad11d1f"
},
{
"id": 15,
"entityId": 1,
"isActive": true,
"onTableType": "PROFILE_TABLE",
"onTableId": "45",
"onFields": [
"lastName",
"customerId",
"addressLocality"
],
"eventType": "CREATE",
"targetUrl": "https://webhook.site/eb2e5173-d315-49d5-9ab8-a12b652067ed"
}
]

L'opération GET/entity/{e}/webhooksubscription/{wh} donne une structure de réponse similaire, avec les détails de la définition de l'abonnement Webhook. La différence est qu'elle ne vise qu'un seul abonnement, dont il est nécessaire d'utiliser l'identifiant en paramètre.

Modifier un abonnement

Vous pouvez modifier un abonnement Webhook existant grâce à l'opération PUT/entity/{e}/webhookSubscription/{wh}

Les paramètres à utiliser pour cela sont l'entité et l'identifiant de l'abonnement Webhook, tel que vous l'avez obtenu à sa création ou que vous avez pu récupérer grâce à l'opération précédente.

Il faut ensuite renseigner les modifications dans le paramètre "webhookSubscription".

Ne pourront être modifiés que :

  • Le caractère actif de l'abonnement ("isActive").

  • L’information "onFields" (c'est-à-dire la liste des champs écoutés). Il est nécessaire d'indiquer la liste complète des champs concernés, pas uniquement les ajouts.

  • Le mode utilisée pour pousser l'information ("webhookPushType" : ONE_BY_ONE ou BULK). Pour les Webhook de type BULK, il faudra aussi préciser la valeur du "maxBlockSize".

Exemple d'ajouts de champs écoutés et la réponse : (Téléchargez cet exemple)

PUT/entity/{e}/webhooksubscription/{wh}
Curl call
curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"isActive\": true,
\"onFields\": [\"customerId\", \"firstName\", \"lastName\", \"birthDate\",\"motherLanguage\"]
}" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/webhookSubscription/15"
 
Response body
{
"id": 15
}

La réponse à la mise à jour d'un abonnement Webhook est son identifiant.

Supprimer un abonnement

Il est possible de purement et simplement supprimer un abonnement. Plus aucun événement ne sera alors écouté.

Pour cela, il faut utiliser l'opération DELETE/entity/{e}/webhookSubscription/{wh} en renseignant l'entité et l'identifiant technique de l'abonnement Webhook en paramètre.

Récupérer un fichier d'erreurs

Typiquement, les erreurs éventuelles liées aux Webhook sont liées à l'URL indiquée pour recueillir l'information. Il se peut que celle-ci ne soit pas adaptée ou temporairement inaccessible.

Il est possible de récupérer un fichier d'erreurs pour une date précise. Il faut pour cela utiliser la méthode GET/entity/{e}/webhookSubscription/{wh}/{date}

Les paramètres suivants doivent être renseignés :

  • L'entité

  • L'identifiant technique de l'abonnement Webhook

  • La date, au format AAAA-MM-JJ. Il est obligatoire de préciser la date pour laquelle vous voulez obtenir les erreurs.

Le fichier ainsi obtenu est un fichier texte reprenant les informations techniques de l'abonnement ainsi que les données sur des champs écoutés qui auraient dû normalement être renseignés s'il n'y avait pas eu d'erreur.

Astuce

Téléchargez un exemple de fichier d'erreur : webhookErrors.txt