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 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://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 it can be used to connect different webhook events to different transactions, currently only used for events triggered via the Paywall functionality.

  • source: specify the source of the triggered event, currently only used for events triggered via the Paywall functionality.

  • 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 manual via the UI.

Error notifications

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

Webhooks list

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, that 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.

  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 
}
PreviousInsights APINextSubscription guide

Last updated

Was this helpful?