Registering a WebHook to receive consent event updates
To stay current on any event in the consent lifecycle, you must register a webhook API to receive the update information.
The webhook endpoint must be in the POST method , under https. The domain and URI can be in whatever format you have on your platform, for the examples below we will consider the POST endpoint examplehttps://www.my-domain.com/webhook
After implementing this API on your platform, you need to register it to receive notifications via our webhook registration API.
But to access this API, you need to perform a previous step, which is to authenticate using your application's credentials. We will describe the step by step in this topic.
Access Token Request (using My First App credentials)
curl --location --request POST 'https://onboard.smartkeys.celcoin.dev.fsapps.io/api/portal/onboard/v1/token' \ --header 'Content- Type: application/json' \ --data-raw '{ "client_id":"64b51075-45bf-46cc-aed4-29b69b51816d", "client_secret": "9257b897-01ca- 4ebd-9fd4-************"}'
Access Token Response
{
"access_token": "**********NiIsInR5cCIgOi********lkIiA6ICJSY0hYOGx********V9JQUFEUm1pSzV5SWlnW "expires_in": 3600,
"refresh_expires_in": 0, "token_type": "Bearer", "not-before-policy": 0, "scope": "email profile"
}
Now you need to get the contents of the "access_token" parameter and include it as an Authentication Bearer header for all future API calls.
Once the access_token is generated, let's register your webhook using the request below.
Webhook Registration API
curl --location 'https://onboard.smartkeys.celcoin.dev.fsapps.io/api/smart-keys/interceptors' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{your_generated_access_token_here}}' \
--data '{
"endpoint": "https://www.my-domain.com/webhook",
"isAuthenticated": false,
"authenticationType": "",
"user": "",
"password": "",
"type": "PAYMENT"
}'
The request will return the following Http status codes.
HTTP Status Code |
|
|---|---|
201 | Webhook succesfully registered. |
400 | Bad Request - error at request field validations. |
401 | The used token is not allowed to access the resource. |
That is all! Now, on any consent status update, the POST https://www.my-domain.com/webhook API will get a request with the body field as below:
{
"event": "before:consent:create",
"data": { ... }
}
The data field provides details about the consent event. The field event brings the new consent status, which can be one of the possibilities below.
Event | Details |
|---|---|
before : consent : create | We received a request for a consent build. |
after : consent : create | All consent fields have been validated, it is following all necessary standards and has been created. |
consent : approved | Consent has been approved by the user. |
consent : rejected | Consent was rejected by the user. |
consent : consumed | The consent was consumed by the Financial Institution. |
consent : polling | Survey to verify the payment situation at the Financial Institution. |
consent : finish | The money was transferred successfully or there was an error reported by one of the Financial Institutions involved in the transaction. More information is provided within the data field. |
consent : expired | The consent has expired. Was not approved or rejected after 5 minutes of creation OR after approval/rejection was not consumed within 70 minutes. |
consent : revoke | User revoked consent (usually after approval) |
Testing the webhook
To test the WebHook process, it can also be configured in the Endpoint Management section of the development portal. We will use the WebHook Site (https://webhook.site/ ) to simulate the process. The site will generate a WebHook URL as shown below.
Copy the generated WebHook URL and register in the Application Settings under the "Endpoint Management" section. You must insert it as a POST method and you will receive a Json in the body.
Then click on the Save button .