Managing Webhook Subscriptions

Managing existing Webhook subscriptions is done through the 'webhook-controller' category of the ACTITO APIs.

With the help of the various existing operations, you will be able to search for Webhook subscriptions, modify them, delete them, as well as retrieve the error file for a specific date.

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

Searching for subscriptions

It is possible to obtain the list of every subscription to a Webhook for a given entity through the operation GET/entity/{e}/webhookSubscription

This feature will allow you to obtain:

  • The technical id of the Webhook subscription, which will be used as parameter in operations used for update and deleting a subscription.

  • The details of the Webhook subscription definition. These are the table, the event type and the fields to which you are listening, as well as the address to which the event notifications will be sent.

The only parameter that you will need to provide is the entity whose Webhook subscriptions you want to obtain. However, several filters allow you to refine your selection:

  • "tableType": CUSTOM_TABLE or PROFILE_TABLE

  • "tableId": You will need to use the technical id of the table, which can be retrieved via the ACTITO interface or through Webservices

  • "eventType": Allows you to filter subscriptions according to their types (CREATE, UPDATE,...)

  • "isActif": This filter allows you to only display active Webhooks

  • "webhookEndPointId": You can search for the URL on which the events are posted

  • "page" and "pageSize": These are the page parameters. The first page is page number 0. "PageSize" restricts the amount of subscriptions displayed per page

  • "sort" and "sortDirection": These parameters allow you to sort subscriptions depending on parameters detailed above and specify whether they will be displayed in ascending or descending order.

Example of a request and its result: (Download this example)

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"
}
]

The operation GET/entity/{e}/webhooksubscription/{wh} gives a similar response structure, with details about the definition of the Webhook subscription. The difference is that it only targets one subscription, whose id needs to be used as parameter.

Modifying a subscription

You can modify an existing Webhook subscription through the operation PUT/entity/{e}/webhookSubscription/{wh}

The parameters you have to use are the entity and the id of the Webhook subscription. This id can be obtained after its creation or retrieved through the previous operation.

Next, you can will need to specify the modifications in the "webhookSubscription" parameter.

You will only be able to modify:

  • Whether the subscription is active ("isActive")

  • The "onFields" information (which is the list of fields to which you are listening). It is necessary to provide the whole list of listened fields, not only the additions.

  • The mode used to push the information "webhookPushType": ONE_BY_ONE or BULK). For BULK Webhooks, you will also have to specify the value of the "maxBlockSize".


Example of field addition and of the response: (Download this example)

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
}

The response to the modification of a Webhook subscription is its id.

Deleting a subscription

It is possible to completely delete a subscription. In this case, you will not listen to any event anymore.

To do so, you need to use the operation DELETE/entity/{e}/webhookSubscription/{wh} and provide the entity and the technical id of the Webhook subscription as parameter.

Retrieving an error file

Typically, potential errors in relation to Webhook are linked to the URL used to collect the information. This address might be unsuitable or temporarily unavailable.

It is possible to retrieve an error file for a specific date. To do so, you need to use the method GET/entity/{e}/webhookSubscription/{wh}/{date}

Required parameters are as follows:

  • The entity

  • The technical id of the Webhook subscription

  • The date, with the YYYY-MM-DD format. Specifying the date for which you want to retrieve the errors is mandatory.

The file you will obtain is a text file with the technical information related to the subscription, as well as all the data about fields which should have been posted on the URL if there was no error.

Tip

Download an error file example: webhookErrors.txt