Webhooks

Overview

Webhooks allows you to notify your downstream systems when relevant events are raised by Socotra. Here are some examples how webhooks can be used:

  • Triggering integration processes, such as printing and sending an invoice after it is issued

  • Enabling automated processes, such as a renewal process after a policy nears expiration

  • Capturing data changes for maintaining an external database that includes Socotra data

For each external system to be notified, you’ll create a webhook using an External Service Integration. Each webhook will listen for a set of events and notify its associated external system when any event in the webhook event set is raised.

The webhook endpoint will create (or update, if a webhook with that name exists) a webhook definition.

Setting Up Webhooks

Setting Up External Service Integrations

External service integrations provide a gateway for Socotra to communicate with external system. Each webhook will use an ESI, so you’ll need to establish those first. To establish and manage webhook integration points, use the External Service Integration API and create an integration with type webhook.

Webhook Management API

After you establish your external service integration, you can use these endpoints to create webhooks.

Create or Update a Webhook
PUT /webhooks
FailureHandlingRequest
optional
actOnStatusCodes [string]
actOnTimeout boolean
failureHandlingMode string none | divert | suspend
failureIntegrationName string
resetFailureIntegrationName boolean
FailureHandlingResponse
required
actOnStatusCodes [string]
actOnTimeout boolean
failureHandlingMode string none | divert | suspend

optional
failureIntegrationName string
WebhookRequest
required
name string

optional
enabled boolean
events [string cancellation.create | cancellation.update | cancellation.rescind | cancellation.issue | claim.close | claim.create | claim.discard | claim.open | claim.update | policy.gracePeriod | policy.gracePeriod.update | invoice.issue | invoice.invalidate | invoice.pastDue | payment.pay | policy.cancel | policy.create | policy.discard | policy.endorse | policy.finalize | policy.issue | policy.lapse | policy.reinstatement.close | policy.reinstatement.invoice | policy.reinstatement.issue | policy.reinstatement.open | policy.renew | policy.update | policy.upgrade | subClaim.open | subClaim.update | subClaim.close | subClaim.reopen | subClaim.updateReserve | policy.end.reminder | subClaim.createPayable | subClaim.reversePayable | endorsement.create | endorsement.update | endorsement.quote | endorsement.accept | endorsement.issue | endorsement.invalidate | endorsement.discard | reinstatement.accept | reinstatement.create | reinstatement.issue | reinstatement.invalidate | reinstatement.deadlineReached | renewal.create | renewal.update | renewal.quote | renewal.accept | renewal.issue | renewal.invalidate | renewal.discard | policy.end | policy.quote.create | policy.quote.discard | policy.quote.update | policy.quote.quoted | policy.quote.accept | policy.quote.declined | policy.quote.invalidate | premiumReport.create | premiumReport.update | premiumReport.issue | premiumReport.discard | premiumReport.reverse | premiumReport.replace | login.success | login.failure | policyholder.create | policyholder.update | payment.reverse | policy.gracePeriod.satisfied | webhook.suspended]
failureHandling FailureHandlingRequest
integrationName string
retryStrategy string none | one | three
WebhookResponse
required
name string
enabled boolean
events [string cancellation.create | cancellation.update | cancellation.rescind | cancellation.issue | claim.close | claim.create | claim.discard | claim.open | claim.update | policy.gracePeriod | policy.gracePeriod.update | invoice.issue | invoice.invalidate | invoice.pastDue | payment.pay | policy.cancel | policy.create | policy.discard | policy.endorse | policy.finalize | policy.issue | policy.lapse | policy.reinstatement.close | policy.reinstatement.invoice | policy.reinstatement.issue | policy.reinstatement.open | policy.renew | policy.update | policy.upgrade | subClaim.open | subClaim.update | subClaim.close | subClaim.reopen | subClaim.updateReserve | policy.end.reminder | subClaim.createPayable | subClaim.reversePayable | endorsement.create | endorsement.update | endorsement.quote | endorsement.accept | endorsement.issue | endorsement.invalidate | endorsement.discard | reinstatement.accept | reinstatement.create | reinstatement.issue | reinstatement.invalidate | reinstatement.deadlineReached | renewal.create | renewal.update | renewal.quote | renewal.accept | renewal.issue | renewal.invalidate | renewal.discard | policy.end | policy.quote.create | policy.quote.discard | policy.quote.update | policy.quote.quoted | policy.quote.accept | policy.quote.declined | policy.quote.invalidate | premiumReport.create | premiumReport.update | premiumReport.issue | premiumReport.discard | premiumReport.reverse | premiumReport.replace | login.success | login.failure | policyholder.create | policyholder.update | payment.reverse | policy.gracePeriod.satisfied | webhook.suspended]
failureHandling FailureHandlingResponse
integrationName string
retryStrategy string none | one | three
suspended boolean

optional
suspendedTimestamp timestamp
Get all Webhooks
GET /webhooks
WebhooksResponse
required
webhooks [WebhookResponse]
Get a Webhook
GET /webhooks/{name}
    Request:
    NamePositionTypeRequired
    namepathstringrequired
    Response: WebhookResponse
Delete a Webhook
DELETE /webhooks/{name}
    Request:
    NamePositionTypeRequired
    namepathstringrequired
    Response: void

{{@Unsuspend a suspended Webhook|unsuspendWebhookUsingPATCH}}

Note

Webhooks can be created and managed through the admin user interface.

All the above /webhooks endpoints will require admin user access. This requirement is the same as the requirement for setting up the external service integrations that the webhooks will use.

Note

The names for each event will be the name as shown elsewhere in the documentation, such as, "policy.create" or "endorsement.update".

Behavior

After each event is fired, Socotra will scan all webhooks, and for each one that is enabled and not suspended, and for which the event is included in the events property:

  • POST the WebhookEvent object to the associated External Service Integration for that webhook.

  • On timeout or non-200 responses from the call, invoke error handling as discussed below.

WebhookEvent
required
eventType string cancellation.create | cancellation.update | cancellation.rescind | cancellation.issue | claim.close | claim.create | claim.discard | claim.open | claim.update | policy.gracePeriod | policy.gracePeriod.update | invoice.issue | invoice.invalidate | invoice.pastDue | payment.pay | policy.cancel | policy.create | policy.discard | policy.endorse | policy.finalize | policy.issue | policy.lapse | policy.reinstatement.close | policy.reinstatement.invoice | policy.reinstatement.issue | policy.reinstatement.open | policy.renew | policy.update | policy.upgrade | subClaim.open | subClaim.update | subClaim.close | subClaim.reopen | subClaim.updateReserve | policy.end.reminder | subClaim.createPayable | subClaim.reversePayable | endorsement.create | endorsement.update | endorsement.quote | endorsement.accept | endorsement.issue | endorsement.invalidate | endorsement.discard | reinstatement.accept | reinstatement.create | reinstatement.issue | reinstatement.invalidate | reinstatement.deadlineReached | renewal.create | renewal.update | renewal.quote | renewal.accept | renewal.issue | renewal.invalidate | renewal.discard | policy.end | policy.quote.create | policy.quote.discard | policy.quote.update | policy.quote.quoted | policy.quote.accept | policy.quote.declined | policy.quote.invalidate | premiumReport.create | premiumReport.update | premiumReport.issue | premiumReport.discard | premiumReport.reverse | premiumReport.replace | login.success | login.failure | policyholder.create | policyholder.update | payment.reverse | policy.gracePeriod.satisfied | webhook.suspended
createdTimestamp timestamp
createdBy string
isDeleted boolean
isNotDeleted boolean
tenantLocator string
webhookLocator string

optional
deletedTimestamp timestamp
deletedBy string

Note

Events sent within each webhook will be ordered based on the timestamp on the event response. Events for the same webhook will be sent serially, not concurrently. If there are multiple webhooks for same event type, the different webhooks may be triggered in parallel. For example, if events A and B are sent to both webhook 1 and 2, then webhook 1 may be sent event B before webhook 2 is sent event A.

The data property contains the same information as is returned in the Event Stream API.

Error Handling

If the external service responds with a non-2xx HTTP response, or does not respond with 120 seconds, the message will be considered failed and retry protocols will ensue.

On failure, the webhook’s retryStrategy property will be used to determine the course of action:

  • none: The failure will be silently ignored and the system will act as if the message had succeeded

  • three: The system will try three more times, each 60 seconds apart. If any of these succeed, the operation will be considered to have succeeded. Note: subsequent messages will not be sent once one succeeds.

If no message succeeds during the retry attempts, then the webhook’s suspended property will be set to true, and the event stream will emit a webhook.suspended event. That webhook will remain inactive until the user unsuspends the webhook.

Event Stream

When a webhook becomes suspended, the webhook.suspended event will fire with this payload:

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

Note

In an upcoming release, Socotra will offer a “Replay” feature, such that messages not sent while a webhook is suspended will be saved and able to be resent after the the webhook is reestablished.