Events enables external systems to send and receive events. An external system could be BriteCore as a site, a customer's own system, or a vendor. Once the event is received, our products (Quote, Claims, IntegrationX, etc.) can react to that event. Example: When a payment is made within Invoice Cloud's system, you can send a message to Events with the data about the payment. Accounting could listen for that event and record it in the GL. Any customer can, through the API, create an event subscription (e.g., webhook) that allows BriteCore products to send events to a validated external system.
What events are available?
Refer to the Events Reference page
Create a subscription
To create an event subscription, you send a POST to /events/subscriptions with the URL to receive the events and the selector string of events you would like to subscribe to receive. The JSON data is structured in JSON:API
[expand title="View code" swaptitle="Hide code" trigclass="trigbar"]
{"data": { "type": "subscription", "attributes": { "url": "https://myorg.com/events", "events": "bc.demo.event" } }} [/expand] The URL should implement the protocol described by AWS for subscribing to SNS over HTTPS. This is left to the subscriber to complete. The event string selector determines which events are matched as they go through the event bus. AWS EventBridge is used for this and the possible pattern matching operations are detailed in the EventBridge documentation. The creation of a subscription can take a few minutes. As such, an HTTP 202 ACCEPTED response code is returned in accordance with JSON:API. You can check the status of the subscription by querying the list subscription's API. Only confirmed subscriptions are returned.
Select/Filter events
The events field of a subscription will only be applied to the source field of the event (the above AWS documentation refers to more than that). Three common patterns are a string match, prefix match, and anything-but. A string match is the full string of the source, whereby it's the same in the event subscription and event; for example, bc.demo.event. “{“prefix”: “bc.policies”}” Note: We automatically add brackets `[ ]` around the event string. Including them will cause an asynchronous error and your subscription will not become active.
Publish an event
External systems may publish events into BriteCore using the publishing endpoint. Send a POST to /events/ with a payload of:
[expand title="View code" swaptitle="Hide code" trigclass="trigbar"]
{ "data": { "type": "event", "attributes": {"source": "home.brewed.event", "detail": {"what": "ever"}} } } [/expand] The detail must be JSON compatible and less than 256 KB.
Publish an event greater than 256 KB
Events greater than 256 KB must be sent with an upload: true attribute.
[expand title="View code" swaptitle="Hide code" trigclass="trigbar"]
{ "data": { "type": "event", "attributes": {"source": "home.brewed.event", "detail": {}, "upload": "true"} } } [/expand] The response will contain a pre-signed S3 link in the Location header, where you must upload the event payload (that which otherwise would have gone in the detail attribute).
View the 50 latest events that were sent to a subscription
Messages will automatically be deleted after three months. Previous messages in the database will show an expires or None. Use the API endpoint list_subscription_messages.
[expand title="View code" swaptitle="Hide code" trigclass="trigbar"]
requests.get(f"https://api.customer.britecore.com/events/subscriptions/ec5d5df3-2016-4423-8172-229171a5d86d/messages", headers=headers)
{
'data': [
...{
'attributes': {
'attempts': 1.0,
'delivery_id': 'abc18b700-2222-3333-4444-eff20f0111111',
'destination': 'https://api.exmpale.com/incoming',
'duration': 107.0,
'dwell_time_ms': 107.0,
'expires': < unix epoch time 'provider_response': 'Accepted',
'status_code': 202.0,
'timestamp': '2021-04-01 22:22:22.22',
'topic_arn': 'arn:aws:sns:us-east-1:123456789070:subscription-abc18b700-2222-3333-4444-eff20f0111111-Topic'
},
'id': 'abc18b700-2222-3333-4444-eff20f0111111',
'relationships': {
'subscription': {
'links': {
'related': '/events/subscriptions/abc18b700-2222-3333-4444-eff20f0111111'
}
}
},
'type': 'subscription-message'
},
{
'attributes': {
'attempts': 1.0,
'delivery_id': 'abc18b700-2222-3333-4444-eff2222111111',
'destination': 'https://api.exmpale.com/incoming',
'duration': 74.0,
'dwell_time_ms': 74.0,
'expires': None,
'provider_response': 'Accepted',
'status_code': 202.0,
'timestamp': '2021-03-16 12:12:12.12',
'topic_arn': 'arn:aws:sns:us-east-1:123456789070:subscription-abc18b700-2222-3333-4444-eff2222111111-Topic'
},
'id': 'abc18b700-2222-3333-4444-eff2222111111',
'relationships': {
'subscription': {
'links': {
'related': '/events/subscriptions/abc18b700-2222-3333-4444-eff2222111111'
}
}
},
'type': 'subscription-message'
}
],
'links': {
'self': '/events/subscriptions/abc18b700-2222-3333-4444-eff2222111111/messages'
},
'meta': {
'count': 50
}
}
[/expand]
Limits
Size
Events greater than 256 KB must be sent with an upload: true attribute. The sender may follow this example to roughly determine the size of the event. Sending events with payloads greater than 256 KB will fail to be published if the upload attribute is missing.
Subscriptions
Leveraging several AWS products, subscriptions take about a minute or two before events start to be delivered. This assumes that the response to the initial SNS delivery request is automatically handled. After approximately 12.5 minutes, without a successful response, attempts to create the subscription will cease. After deleting a subscription, it may take up to a few seconds before events stop being delivered. The subscription is removed from being listed in less than a second. Subscriptions are limited to unique URLs and event selectors, for example, example.com, and bc.demo.event can't be used to subscribe multiple times. An HTTP 409 CONFLICT response code will be given when attempting to do so.