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.

Info icon

Information – The {webhooksBaseUrl} variable isn't your {baseUrl}

  • https://webhook.sandbox.treezor.co in Sandbox
  • https://webhook.api.treezor.co in Production
Gear icon

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)
Bulb icon

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 icon

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'