Webhooks API

Webhooks allows you to notify your downstream systems when relevant events are raised by Socotra.

Endpoint Index

ActionEndpoint
Create or Update a WebhookPUT /webhooks
Get all WebhooksGET /webhooks
Get a WebhookGET /webhooks/{name}
Delete a WebhookDELETE /webhooks/{name}
Enable a suspended WebhookPATCH /webhooks/{name}/unsuspend
Get a paginated list of diverted eventsGET /webhooks/{name}/diverted
Delete a diverted eventDELETE /webhooks/{name}/diverted/{transactionId}
Resend a diverted eventPOST /webhooks/{name}/diverted/{transactionId}/resend

Details

Create or Update a Webhook
PUT /webhooks
WebhookRequest
required
name string

optional
alertIntegrationName 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 | invoice.writtenOff | 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
failureHandling FailureHandlingRequest
integrationName string
resetAlertIntegrationName boolean
retryStrategy string none | one | three

The webhook name must not be longer than 128 characters, and may contain only letters, numbers, and symbols as follows:

  • Alphanumeric characters – the arabic numerals (0 to 9)

  • Latin letters (A to Z, a to z) – and the

  • The hyphen, underscore, and tilde symbols (-, _, ~)

The alertIntegrationName, if provided, will be used to POST the FailureMessage object. See Failure Handling for details.

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 | invoice.writtenOff | 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
failureHandling FailureHandlingResponse
integrationName string
retryStrategy string none | one | three
suspended boolean

optional
suspendedTimestamp timestamp
alertIntegrationName string
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
WebhookPayload
required
id string
timestamp timestamp
transactionId string
type string
username string

Failure Handling

FailureMessage
required
actualStatus string
eventData EventStreamData
expectedStatus string
url string
webhookName object
FailureHandlingRequest
optional
actOnStatusCodes [string]
actOnTimeout boolean
mode string none | divert | suspend
FailureHandlingResponse
required
actOnStatusCodes [string]
actOnTimeout boolean
mode string none | divert | suspend

Failure handling will be invoked based on the response (or non-response) from the webhook target.

Suspended events

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 | invoice.writtenOff | 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
integrationName string
webhookName string

When a webhook is suspended, a webhook.suspended event will fire with an EventStreamWebhookSuspendedData payload.

The suspended webhook will not receive or process events, and will remain inactive until you reactivate the webhook.

Enable a suspended Webhook
PATCH /webhooks/{name}/unsuspend
    Request:
    NamePositionTypeRequired
    namepathstringrequired
    Response: WebhookResponse
Get a paginated list of diverted events
GET /webhooks/{name}/diverted
    Request:
    NamePositionTypeRequired
    limitqueryintegeroptional
    namepathstringrequired
    offsetqueryintegeroptional

The limit and offset properties are used to page through the list of results, getting batches of diverted events of size limit. Increase the offset property with each query, to skip the events you have already retrieved. The default value of limit is 100, and the default value of offset is 0, so the first call to GET /webhooks/{name}/diverted will return the first 100 diverted events (or fewer if there are less than 100 events).

WebhookDivertedEventsResponse
required
webhookName string
WebhookDivertedEventResponse
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 | invoice.writtenOff | 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
timestamp timestamp
eventId string
transactionId string

optional
username string

After you resolve the webhook failure and re-enable the diverted webhook, you can process the list of diverted events, and POST or DELETE any or all of these events.

Delete a diverted event
DELETE /webhooks/{name}/diverted/{transactionId}
    Request:
    NamePositionTypeRequired
    namepathstringrequired
    transactionIdpathstringrequired
    Response: void
Resend a diverted event
POST /webhooks/{name}/diverted/{transactionId}/resend
    Request:
    NamePositionTypeRequired
    namepathstringrequired
    transactionIdpathstringrequired
    Response: void