Platforms | Event Notifications

Introduction

Event Notification allows building integrations using Capillary events that can originate from Capillary API requests or from Capillary Loyalty+, Engage+ or other products. Examples of events are:-

  • API requests - customerAdded, transactionAdded, etc

  • Loyalty+ Events - pointsIssued, pointsRedeemed, etc


Event Notifications are sent via “Webhooks”. Webhooks can be created from Organization Settings by providing webhook name, URL and headers, and selecting required events. If the events are triggered, an HTTP POST payload is sent in JSON to the webhook's configured URL. 

Use Cases

There can be multiple use cases for Event Notifications. Few of them are listed below:

Enabling PII-less Communication

Sometimes, clients (or brands) can choose to not send customer’s PII data (names, or identifiers such as email, mobile, etc) to Capillary, and manage communication completely at their end. Event Notification can be used to get the events which require communication such as customer registration, transaction, points issual, points redemption, points transfer, etc. On receiving these events, clients can send communication to customers with their names and identifiers as they want.

Integration with 3rd Party Applications

Event notification can be used for building integrations with 3rd party applications. E.g. Sending a survey link to a customer post transaction event from a survey application such as Medallia; syncing customer’s loyalty information to an ecommerce platform such as Magento. Integration can be built to receive Capillary events in real-time, enrich the information by calling Capillary APIs (if required), and sync it to the 3rd party application by calling its APIs.

Setting up Event Notification

1. Create Webhook account.

2. Edit Webhook if required. You can also deactivate a Webhook account if not required.

3. Test the configured Webhook using any of the free webhook testing sites. Search for “test webhooks online”, or visit https://requestbin.com/

For example:

  1. Generate Webhook endpoint from the site.

  2. Copy the Webhook endpoint created or displayed on the test site, and use it to create a Webhook in Capillary Event Notification. While creating the Webhook, select customer or transaction events, which can be triggered by API requests.

  3. Make an API request by calling customer/add or transaction/add APIs.

  4. If Event Notification has been set up appropriately, event will be received on the test site

4. Consume the configured event.


Consuming Event Notification

Authentication

Every event is sent with the Webhook’s configured authentication header. The authentication shall be used by the integration to authenticate the webhook.


Events Replay

In order to ensure events get delivered to the Webhook’s configured URL, Event Notification waits for a successful response from the server for 30 seconds. If the response is not received, the event is marked as timed-out. Timed-out events are replayed continuously till success or 24 hours, whichever happens first.


Events are replayed also when a 5xx error response is received from the server or integration backend. Events are not replayed if a 4xx error response is received.

Idempotency Check

There can be situations where an event is received by the server, but a successful response is not sent back to Capillary. These cases are considered as timed-out events, and events are sent again to the Webhook URL. Hence, the integration backend or server should be able to handle the same event multiple times.


The duplicate events can be identified using the field “eventId” in the event payload:


{

    "eventName": “customerAdded”,

    "eventId": “GSjhsJ87484SdghD4747”,

    “orgId”: 1655

    “refId”: “1655_684494987”,

    “apiRequestId”: “sdjsj78378d3287”,

    "createdAt": 156474848484,

}


If the “eventId” is duplicate, the event should be ignored.


Data Enrichment

Event Payload contains short and optimal information. It does not contain complete information about the entities. E.g. Transaction events contain identifiers and basic transaction information, but do not contain custom or extended fields information or line item level information. To get complete information about an entity, APIs should be called.


Change Data Capture

Update events such as customerUpdated, transactionUpdated, etc only notify that some update has occurred in the associated entities. They do not contain the information about the change in the entities. To identify change, APIs would need to be called by the integration service.

Troubleshooting

To get event log, use following APIs:

  1. Get event log by eventId - {Host URL}/v3/webHooks/eventLog/{eventId}

  2. Get event log by API Request Id - {Host URL}/v3/webHooks/eventLog/requestId/{requestId}


Login to post a comment