Subscription management
Webhook reception requires you subscribe to them first. While a single subscription allows you to receive all webhooks, you can also register multiple endpoints to receive different events.
During the subscription, if you don't specify an explicit list of webhooks that you whish to receive, you will automatically subscribe to all events.
Information – The {webhooksBaseUrl}
variable isn't your {baseUrl}
https://webhook.sandbox.treezor.co
in Sandboxhttps://webhook.api.treezor.co
in Production
Configuration – You may need assistance for your {accessToken}
While the {accessToken}
should be either your BaaS API key or your Connect JWT token, webhook subscription may require an action from Treezor. Contact your Treezor Implementation Manager for more information.
Declare a POST route in your back end
In your back end, you should define a route that accepts HTTP POST requests.
Below is an example using node.js/express:
js
const express = require('express');
const app = express();
const bodyParser = require('body-parser');
// parse the application/json
app.use(bodyParser.json());
// expose a POST endpoint
app.post('/webhook', function (req, res) {
// log each call (will be necessary to manually confirm the endpoint, step 3)
console.log(JSON.stringify(req.body));
});
// start listering for webhooks
app.listen(3000, function () {
console.log('Example app listening on port 3000!')
});
Then deploy this endpoint to a server:
- Which is reachable from internet
- On which you can consult the logs (to confirm your subscription at a later stage)
Tip – Making your development server reachable from internet
Several options are available to you to make your development server reachable from internet. See the Testing in Sandbox article for more information.
Register a hook endpoint
The second step is to register your newly created endpoint using the following request.
bash
curl -X POST {webhooksBaseUrl}/settings/hooks \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{"url":"{urlOfYourEndpoint}"}'
Returns the list of webhooks including the newly created one with a temporary uuid
in a pending status. Its uuid will change when the subscription is validated later on.
json
{
"hooks":[
{
"uuid":"d956cff0-04a2-530f-810b-66a5130e0e4a",
"url":"{urlOfYourEndpoint}",
"status":"PENDING"
}
]
}
You are now receiving new events.
List your webhooks subscriptions
You can list your subscriptions using the following request.
bash
curl --get {webhooksBaseUrl}/settings/hooks \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
Outputs a list of subscriptions, including their uuid (uuid
) and status (status
).
json
{
"hooks":[
{
"uuid":"44c37ba5-f1fe-4d8a-ac2b-xxxxx6a2ae67",
"url":"https:\/\/0***l.execute-api.eu-west-3.amazonaws.com\/dev\/aHR...3Q=",
"status":"ENABLED"
},
{
"uuid":"cd98d460-f344-4c05-a192-xxxxxf6c0a4a",
"url":"https:\/\/toto:****@0***l.execute-api.eu-west-3.amazonaws.com\/dev\/aHR...3Q=",
"status":"ENABLED"
},
{
"uuid":"46a508cb-1c72-48be-a42d-xxxxxa704cec",
"url":"https:\/\/toto:****@0***l.execute-api.eu-west-3.amazonaws.com\/dev\/aHR...Hk=",
"status":"ENABLED"
},
{
"uuid":"0fae6471-25c3-4492-bc0d-xxxxx82e51ec",
"url":"https:\/\/toto:****@trz.requestcatcher.com\/tututu",
"status":"ENABLED"
}
]
}
Retrieve details about a subscription
You can retrieve the list of events to which a webhook is subscribed to, using the following request.
bash
curl --get {webhooksBaseUrl}/settings/hooks/{webhookUuid}/events \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json'
Outputs a list of events to which you have subscribed.
json
{
"events":[
"payoutRefund.cancel",
"payoutRefund.create",
"payoutRefund.update"
]
}
Note – An empty array is returned when you subscribed to all webhooks
The list of events is only relevant when you subscribed to specific webhooks.
Update a subscription
To add more events
You only have to specify the new events in the payload, there is no need to specify already subscribed to events.
bash
curl -X POST {webhooksBaseUrl}/settings/hooks/{webhookUuid}/events \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{"events":[
"beneficiary.update",
"beneficiary.create"
]}'
Outputs the list of subscribed events, including the newly added ones.
To remove some events
You can remove one event at a time, specifying its name in the URL.
bash
curl -X DELETE {webhooksBaseUrl}/settings/hooks/{webhookUuid}/events/{eventToDelete} \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json'
Returns the list of subscribed events, without the one just removed.
Unsubscribing from legacy system
The webhooks management and subscription described on this page is the only recommended method as of 2022.
If you have previously subscribed to webhooks via Connect, please:
- Resubscribe using the procedure described on this page,
- Ensure proper reception of these new webhooks,
- Unsubscribe to webhooks via Connect using the following request (this will not affect your new subscriptions)
Below and example (the {baseUrl}
is your usual Connect base URL).
bash
curl -X DELETE {baseUrl}/hook-settings/settings/hooks/{webhookUuid} \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json'