Webhooks

Webhooks are used to build near real-time integrations with API's and other Saas services. When a business event happens in Younium, a webhook event is placed in a queue that when executed will notify subscribers with an HTTP POST request. The request contains relevant information about the business event for the subscriber to use in the receiving system or platform.

An alternative to Webhooks is to make scheduled API requests on a frequent basis, using Webhooks is more efficient and normally provides a much better user experience.

The events that trigger a webhook may come from any source, meaning that that calls to the API, users actions in the UI as well as integrations will trigger the webhook.

Available webhooks

Subscribing to webhook event

Subscribing to webhook events can be done in the Younium app in settings>webhooks or using the API webhook endpoint.
The endpoint takes two parameters in the body: URL and Events. Events is a list of Event Tags, see Event tags in the table above.

Example (Sandbox):

POST <https://apisandbox.younium.com/Webhooks>

Headers:

Authorization: Bearer [JWT token] Content-Type: application/json

Body:

{ 
  "url": "<https://your-service-url.com>", 
  "events": [ "AccountChanged" ] 
}

Response:

{ 
   "id": "49d5c950-925c-4863-f731-08dabe4f3d15", 
   "url": "<https://your-service-url.com>", 
   "events": [ 
      "AccountChanged", 
      ... //List of events that the webhook will listen to. 
   ], 
   "token": "g67g5fd7-s7d0-32a5-bd7e-df0dwas67c6", //All triggered webhook requests will contain this token. 
   "webhookStatus": "Enabled" 
}

Webhook request body

Example of a webhook request body:

{ 
  "token": "g67g5fd7-s7d0-32a5-bd7e-df0dwas67c6", //Token to verify the request. 
  "eventId": "evt_sRzF5t6yO5DUdaDTM7da7s8EA", 
  "eventType": "AccountChanged", 
  "legalEntityName": "Legal-Entity-Name", 
  "legalEntityId": "rw8710de-5327-41a8-s32c-032s71db86ac", 
  "timestamp": "2022-11-03T14:00:55Z", 
  "triggeredBy": "et0771b7-3wr6-3s6a-a75e-7650910e6787", 
  "data": {...} //Entity-specific data, see requestBody links in the availabel webhooks list for reference. 
}

Webhook request attempts and delivery

When a webhook event is executed a webhook attempt is created and a POST request is sent to the subscribing URL. In order for the attempt to be successful this request will require a successful response (response code 2xx). Any other response will be handled as a failed attempt. In the table below statuses for a failed webhook attempt are listed with descriptions.

The logs for webhook attempts can be found in settings>webhooks in the Younium app and will show all attempted requests over the past 15 days.

Automatic and manual retries

If a webhook request fails it will automatically be resent every third hour until attempted retries reach 10 times. After that, it will need to be resent manually from the app.

Error Notifications

Notifications can be enabled in settings > notifications if a webhook request fails, notifying a user via the app notifications.