Webhooks

Resources on Younium webhooks.

Understanding Webhooks in Younium

Webhooks enable real-time integrations with APIs and other SaaS services. When a business event occurs in Younium, a webhook event is queued, which, upon execution, sends an HTTP POST request to notify subscribers. This request includes details about the business event for the subscriber to process in their system or platform.

While alternatives like scheduled API requests exist, webhooks are generally more efficient and enhance the user experience. Events that trigger a webhook can originate from various sources, including API calls, user actions in the UI, and other integrations.

Subscribing to webhook events

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://api.sandbox.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": "a97b4e0c-1b34-4c85-ae2f-3b14d4e4d8c1", 
  "EventId": "evt_sRzF5t6yO5DUdaDTM7da7s8EA", 
  "EventType": "AccountChanged", 
  "LegalEntityName": "Legal-Entity-Name", 
  "LegalEntityId": "57fc6a9f-5c4b-41d3-9b1b-2e1e62f4e3b8", 
  "Timestamp": "2022-11-03T14:00:55Z", 
  "TriggeredBy": "2e1cb02b-054f-4716-b924-8d7a32cbd8ce",
  "CorrelationId": "e1b69c34-5f6f-4e78-b412-9f9d71e2d531",
  "Source": "source" 
  "Data": {...} 
}

• Token: Token to verify the request.

• CorrelationId: When specified, provides an uuid that can be used to connect webhook events to a common transaction.

• Source: specify the source of the triggered event when set.

• Data: Entity-specific data, see request body references in the webhook list.

Webhook request attempts and delivery

Webhook Event Execution

When a webhook event is executed, a webhook attempt is created, and a POST request is sent to the subscribing endpoint. For an attempt to succeed, the request must receive a successful response (status code 2xx). Any other response will be treated as a failed attempt.

Failed Webhook Attempt Statuses

• Client Error 4xx: This indicates a client-side error. It can result from access restrictions (401, 403), validation errors, bad requests (400), or an unfound URL (404).

• Client Server Error 5xx: Errors occur on the client's server, e.g., internal server error (500) or service unavailable (503). This might suggest an error within Younium causing the failure, indicated in the error message if applicable.

• Request Timeout 500: This happens if the client takes too long to respond, causing request cancellation after 60 seconds. Ensure a successful response is returned before executing any complex logic triggered by the webhook request.

Logs of webhook attempts are available under Settings > Webhooks in the Younium UI, showing all attempts from the past 15 days.

Automatic and manual retries

For failed webhook requests, retries occur automatically every three hours, up to 10 attempts. After that, webhooks can be retried manually via the UI.

Error notifications

Notifications can be enabled under Settings > Notifications to allow a user to be notified via the app notifications, if a webhook request fails.

Webhook events using Paywall

The paywall allows Younium customers to automate online subscription sales. This functionality uses webhooks and will require a specific setup.

1. Create a new webhook with the desired URL

2. Add the following events:

   • AccountCreated

   • InvoicePosted

   • PaymentPosted

   • SubscriptionActivated

The webhook request body for events triggered by the paywall will always include the Source: "Paywall" and the CorrelationId connecting the different events to the common transaction. The data provided for each event is listed below. For a full guide to the Paywall, can be found here

Available webhook events

Subscriptions:

1. SubscriptionActivated - Triggered when a new subscription is activated.

2. SubscriptionChanged - Triggered when a new subscription change has been activated. Equivalent to the change Subscription endpoint.

3. SubscriptionUpdated - Triggered when information is edited or when a stock product delivery is made, which doesn't require a change subscription. Equivalent to patch subscription.

4. SubscriptionCancelled - Triggered when a subscription is cancelled.

5. SubscriptionRenewed - Triggered when a subscription is renewed.

6. SubscriptionReverted - Triggered when a subscription is reverted.

7. SubscriptionDeleted - Triggered when a subscription is deleted.

See Subscriptions for request body

SalesOrders:

1. SalesOrderActivated - Triggered when a new sales order is activated.

2. SalesOrderUpdated - Triggered when information is edited or when a stock product delivery is made.

3. SalesOrderDeleted - Triggered when a sales order is deleted.

See Salesorders for request body

Invoices:

1. InvoicePosted - Triggered when an Invoice is posted.

2. InvoiceUpdated - Triggered when an Invoice is updated.

See Invoices for request body

Journals:

1. JournalPosted - Triggered when a Journal is posted.

See Journals for request body

Accounts:

1. AccountsCreated - Triggered when an Account is created.

2. AccountsChanged - Triggered when an Account is edited.

See Accountsfor request body

Quotes:

1. QuoteCreated - Triggered when a Quote is created.

2. QuoteEdited - Triggered when a Quote is edited.

3. QuoteConverted - Triggered when a Quote is converted to an Order.

See Quotes for request body

Payments:

1. PaymentsCreated - Triggered when a payment is created.

2. PaymentsPosted - Triggered when a payment is posted.

See Paymentsfor request body

InvoiceBatches:

1. InvoiceBatchCreated - Triggered when an invoice batch is created.

2. InvoiceBatchPosted - Triggered when an invoice batch is posted.

3. InvoiceBatchCancelled - Triggered when an invoice batch is cancelled.

See Invoicebatches for request body

Products:

1. ProductsCreated - Triggered when a product is created.

2. ProductsUpdated - Triggered when a product is updated (Currently via API only).

3. ProductsDeleted - Triggered when a Product is deleted. Body: Id and confirmation message.

See Products for request body for created and updated event.

ProductDeleted requestbody

{
    message = "product was deleted",
    id = [uuid] //uuid of the deleted product 
}