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
PUT /webhooks
Name | Position | Type | Required |
---|---|---|---|
request | body | WebhookRequest | required |
WebhookResponse
requiredname stringoptionalalertIntegrationName stringenabled booleanevents 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.satisfiedfailureHandling FailureHandlingRequestintegrationName stringresetAlertIntegrationName booleanretryStrategy 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
to9
)Latin letters (
A
toZ
,a
toz
) – and theThe hyphen, underscore, and tilde symbols (
-
,_
,~
)
The alertIntegrationName
, if provided, will be used to POST
the FailureMessage
object. See Failure Handling for details.
requiredname stringenabled booleanevents 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.satisfiedfailureHandling FailureHandlingResponseintegrationName stringretryStrategy string none | one | threesuspended booleanoptionalsuspendedTimestamp timestampalertIntegrationName string
GET /webhooks
WebhooksResponse
requiredwebhooks [WebhookResponse]
GET /webhooks/{name}
Name | Position | Type | Required |
---|---|---|---|
name | path | string | required |
WebhookResponse
DELETE /webhooks/{name}
Name | Position | Type | Required |
---|---|---|---|
name | path | string | required |
void
requiredid stringtimestamp timestampdata EventStreamDatatransactionId stringtype stringusername string
Failure Handling
requiredactualStatus stringeventData EventStreamDataexpectedStatus stringurl stringwebhookName object
optionalactOnStatusCodes [string]actOnTimeout booleanmode string none | divert | suspend
requiredactOnStatusCodes [string]actOnTimeout booleanmode string none | divert | suspend
Failure handling will be invoked based on the response (or non-response) from the webhook target.
Suspended events
requiredevent 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.satisfiedintegrationName stringwebhookName 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.
PATCH /webhooks/{name}/unsuspend
Name | Position | Type | Required |
---|---|---|---|
name | path | string | required |
WebhookResponse
GET /webhooks/{name}/diverted
Name | Position | Type | Required |
---|---|---|---|
limit | query | integer | optional |
name | path | string | required |
offset | query | integer | optional |
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).
requiredevents [WebhookDivertedEventResponse]webhookName string
requiredeventType 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.satisfiedtimestamp timestampdata EventStreamDataeventId stringtransactionId stringoptionalusername 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 /webhooks/{name}/diverted/{transactionId}
Name | Position | Type | Required |
---|---|---|---|
name | path | string | required |
transactionId | path | string | required |
void
POST /webhooks/{name}/diverted/{transactionId}/resend
Name | Position | Type | Required |
---|---|---|---|
name | path | string | required |
transactionId | path | string | required |
void