Appearance

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.

Endpoint: /settings/hooks

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. The uuid changes 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.

Endpoint: /settings/hooks

bash
curl -X GET '{webhooksBaseUrl}/settings/hooks' \
	--header 'Authorization: Bearer {accessToken}'

Returns the list of subscriptions, with their uuid and 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:\/\/alexoak:****@0***l.execute-api.eu-west-3.amazonaws.com\/dev\/aHR...3Q=",
			"status":"ENABLED"
		},
		{
			"uuid":"46a508cb-1c72-48be-a42d-xxxxxa704cec",
			"url":"https:\/\/alexoak:****@0***l.execute-api.eu-west-3.amazonaws.com\/dev\/aHR...Hk=",
			"status":"ENABLED"
		},
		{
			"uuid":"0fae6471-25c3-4492-bc0d-xxxxx82e51ec",
			"url":"https:\/\/alexoak:****@trz.requestcatcher.com\/example",
			"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.

Endpoint: /settings/hooks/{hookUuid}/events

bash
curl -X GET '{webhooksBaseUrl}/settings/hooks/{hookUuid}/events' \
	--header 'Authorization: Bearer {accessToken}'

Returns 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 ​

Update events list ​

Specify the list of events in the payload (including the ones you've already subscribed to if any).

Endpoint: /settings/hooks/{hookUuid}/events

bash
curl -X POST '{webhooksBaseUrl}/settings/hooks/{hookUuid}/events' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

json
{
	"events":[
		"payoutRefund.cancel",
		"payoutRefund.create",
		"payoutRefund.update",
		"beneficiary.update",
		"beneficiary.create"
	]
}

Returns the list of subscribed events as listed in the payload.

json
{
	"events":[
		"payoutRefund.cancel",
		"payoutRefund.create",
		"payoutRefund.update",
		"beneficiary.update",
		"beneficiary.create"
	]
}

Remove an event ​

You can remove one event at a time, specifying its name in the URL.

Endpoint: /settings/hooks/{hookUuid}/events/{eventToDelete}

bash
curl -X DELETE '{webhooksBaseUrl}/settings/hooks/{hookUuid}/events/{eventToDelete}' \
	--header 'Authorization: Bearer {accessToken}'

Returns the list of subscribed events, without the one just removed.

json
{
	"events":[
		"payoutRefund.create",
		"payoutRefund.update",
		"beneficiary.update",
		"beneficiary.create"
	]
}