# Events



The event stream presents a chronological feed of activity within Socotra Insurance Suite, designed to enhance operational efficiency and data management practices in your business ecosystem. It is a pivotal feature for use cases like these:

* Initiating integrated workflows triggered by key events such as invoice issuance.
* Enabling automated routines, such as activating a policy renewal procedure as the expiry date approaches.
* Capturing data changes for storage in a specialized database.

Event Stream Usage [#event-stream-usage]

The event stream offers:

* The ability to <ApiLink name="fetchEvent">fetch a single event</ApiLink>.
* The ability to <ApiLink name="fetchEventsForARequest">fetch all the events for a single API request</ApiLink>.
* <ApiLink name="fetchMultipleEvents">A paginated view of events</ApiLink> in
  the Socotra system, in ascending chronological order. You may include one or
  more options in your initial query, such as filter criteria, time range, and
  page size. You can then use the `pagingToken` to page through additional
  results.

<Callout>
  The `pagingToken` cannot be used in conjunction with any other optional arguments.
</Callout>

<span id="event-payloads" />

Payloads [#payloads]

Most Socotra events are kept deliberately sparse. A few have additional data attached, as described below.

Billing [#billing]

Billing-related events such as delinquency, payment, and invoice generation have a `policyLocators` property with this value:

<ApiSchema name="ListPageResponseULID" />

Relevant policy locators associated with the entity will be included in the `items` array. If the number of items is five or fewer, the `listCompleted` property will be `true`; else, `listCompleted: false` serves as an indicator to fetch comprehensive data from the API if the full set of policy locators is needed for your use case.

<span id="policyStatus" />

Policy Status [#policy-status]

The policy status event includes `newStatuses` and `removedStatuses` properties with the following value:

<ApiSchema name="ListPageResponsePolicyStatus" />

See the [Policy Status Guide](/features/policy-management/policy-status#policy-status-event-stream) for details.

<span id="custom-events" />

Custom Events [#custom-events]

You may configure custom events to emit from your plugin code.

Configuring Custom Events [#configuring-custom-events]

Add your event's definition (<ApiLink name="CustomEventRef" />) to the `customEvents` map in <ApiLink name="ConfigurationRef">your top-level configuration</ApiLink>. Here's an example of such a definition:

```json
{
	// ...,
	"customEvents": {
		"CustomEventTypeA": {
			"type": "custom.event.type.a"
		}
	}
	// ...,
}
```

Custom events must have a type beginning with `custom.`, followed by a sequence of `.`-delimited alphanumeric characters. All custom event `type` definitions must be unique; else, a deployment error will be thrown.

Emitting Custom Events [#emitting-custom-events]

In plugin code, use the `EventsService.getInstance().createEvent(type, data)` call to emit your custom event. The `type` will be `CustomEvent.<YourEventTypeName>`; in the example above, for instance, you would reference the event as `CustomEvent.CustomEventTypeA`.

`data` must be an JSON-serializable object. A simple approach is to pass a map as `data`, as in this example:

```java
// ...
EventsService.getInstance().createEvent(CustomEvent.CustomEventTypeA, Map.of("quote", quote.locator(), "info", "plugin called"));
// ...
```

See Also [#see-also]

* [Events API](/api/events/events): API details, including a list of supported events
* [Event Definitions](/configuration/general-topics/event-definitions): Details about event payloads
* [Webhooks](/configuration/general-topics/webhooks): Details about pushing events to external systems using webhooks
* [Diverted Events API](/api/events/diverted-events): Functionality to handle failed webhook event messages
* [Custom Scheduled Events](/configuration/general-topics/scheduled-events): Feature to create custom events that can be scheduled to run at specific times or intervals


## API Reference

ListPageResponseULID
Properties:
  listCompleted (boolean, required)
  items (ulid[], required)

ListPageResponsePolicyStatus
Properties:
  listCompleted (boolean, required)
  items (Enum[], required)