Application webhooks

Socotra Core supports webhooks to notify external services about certain events raised in Socotra tenant.

To help with complex integrations, Marketplace platform supports automatic registration of webhooks with Socotra Core tenant.

Overview

Webhooks support in Marketplace application aiming to simplify the scenario when developers need to integrate a service and listen to Socotra Core webhooks, but it's either impossible to make changes in 3rd party service to support Socotra's webhook payloads directly or very expensive and time consuming. Developers can build a Marketplace application which knows how to process Socotra webhooks and can adapt incoming events for external service.

In this case, when Marketplace application starts - it automatically registers as webhook destination in Socotra Core tenant and will be receiving events from Core tenant. It has naturally available capabilities (connection and authentication of an integrated Core tenant) to retrieve additional details from a tenant, check some business logic or convert data to a request format for 3rd party application.

Marketplace platform provides a capability to automatically register webhooks in Core tenant when application starts and unregister them when app is being stopped. To use automatic registration, developers need to define webhook endpoints in Marketplace app manifest. Platform then will subscribe starting application, each webhook entry individually, to corresponding events.

App manifest

Webhooks are configured in socotra-app.json manifest file at the following path

{
  "name": "org-name/app-name",
  "version": "0.0.1",
  "socotra": {
    "webhooks": [
      // Collection of webhook objects
    ]
  }
}

Each entry in webhook objects collection is a json object with following properties.

path string (required) - Property which defines which application endpoint will be registered as webhook URL. When application starts - it assigned a public url which looks like abc123.sandbox.outpost.marketplace.socotra.com. During webhook registration url combined with path value and the result https://abc123.sandbox.outpost.marketplace.socotra.com/<path-value> will be registered as url of Socotra Core external integration.

events string[ ] (required) - values from a predefined collection of event names which are supported in Socotra Core WebhookRequest object (see events field). Marketplace manifest supports all events that are supported in Socotra Core, so when this collection is expanded in Socotra Core API - Marketplace app can start subscribing to new events straight away.

Example of app-manifest with configured webhook integration:

{
  "name": "org-name/app-name",
  "version": "0.0.1",
  "socotra": {
    "webhooks": [
      {
        "path": "/webhook-notify",
        "events": [
          "policy.create",
          "policy.renew",
          "policy.quote.create",
          "policy.quote.quoted",
          "policy.quote.accept",
          "policy.quote.declined",
          "policy.quote.discard",
          "invoice.issue",
          "invoice.pastDue",
          "invoice.invalidate"
        ]
      }
    ],
}

Supported events

Currently Socotra Core and Marketplace app supports the following webhook events:

cancellation.create
cancellation.issue
cancellation.rescind
cancellation.update
claim.close
claim.create
claim.discard
claim.open
claim.update
endorsement.accept
endorsement.create
endorsement.discard
endorsement.invalidate
endorsement.issue
endorsement.quote
endorsement.update
invoice.invalidate
invoice.issue
invoice.pastDue
login.failure
login.success
payment.pay
payment.reverse
policy.cancel
policy.create
policy.discard
policy.end
policy.end.reminder
policy.endorse
policy.finalize
policy.issue
policy.lapse
policy.renew
policy.update
policy.upgrade
policy.gracePeriod
policy.gracePeriod.satisfied
policy.gracePeriod.update
policy.quote.accept
policy.quote.create
policy.quote.declined
policy.quote.discard
policy.quote.quoted
policy.quote.update
policy.reinstatement.close
policy.reinstatement.invoice
policy.reinstatement.issue
policy.reinstatement.open
policyholder.create
policyholder.update
premiumReport.create
premiumReport.discard
premiumReport.issue
premiumReport.replace
premiumReport.reverse
premiumReport.update
reinstatement.accept
reinstatement.create
reinstatement.deadlineReached
reinstatement.invalidate
reinstatement.issue
renewal.accept
renewal.create
renewal.discard
renewal.invalidate
renewal.issue
renewal.quote
renewal.update
subClaim.close
subClaim.createPayable
subClaim.open
subClaim.reopen
subClaim.reversePayable
subClaim.update
subClaim.updateReserve