Webhooks API

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

Endpoint Index

Action	Endpoint
Create or Update a Webhook	PUT /webhooks
Get all Webhooks	GET /webhooks
Get a Webhook	GET /webhooks/{name}
Delete a Webhook	DELETE /webhooks/{name}
Enable a suspended Webhook	PATCH /webhooks/{name}/unsuspend
Get a paginated list of diverted events	GET /webhooks/{name}/diverted
Delete a diverted event	DELETE /webhooks/{name}/diverted/{transactionId}
Resend a diverted event	POST /webhooks/{name}/diverted/{transactionId}/resend

Details

Create or Update a Webhook

PUT /webhooks

Request:

Name	Position	Type	Required
request	body	WebhookRequest	required

Response: WebhookResponse

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

Response: WebhooksResponse

WebhooksResponse

required
webhooks [WebhookResponse]

Get a Webhook

GET /webhooks/{name}

Request:

Name	Position	Type	Required
name	path	string	required

Response: WebhookResponse

Delete a Webhook

DELETE /webhooks/{name}

Request:

Name	Position	Type	Required
name	path	string	required

Response: void

WebhookPayload

required
id string
timestamp timestamp
data EventStreamData
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:

Name	Position	Type	Required
name	path	string	required

Response: WebhookResponse

Get a paginated list of diverted events

GET /webhooks/{name}/diverted

Request:

Name	Position	Type	Required
limit	query	integer	optional
name	path	string	required
offset	query	integer	optional

Response: WebhookDivertedEventsResponse

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
events [WebhookDivertedEventResponse]
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
data EventStreamData
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:

Name	Position	Type	Required
name	path	string	required
transactionId	path	string	required

Response: void

Resend a diverted event

POST /webhooks/{name}/diverted/{transactionId}/resend

Request:

Name	Position	Type	Required
name	path	string	required
transactionId	path	string	required

Response: void