How to validate ESS Webhooks Notifications – Syniverse Developer Community

Syniverse SDC portal provide the UI to the Event Subscription Service (ESS) that allows the enterprise to create subscriptions to Events Notifications. The notifications are defined in terms of where (webhooks) and how (format) described by “Delivery Configuration” and What (Event topics and conditions) described in “Subscriptions”. For detailed information on how to setup Webhooks follow the guidelines described here.

After setting up the required webhooks, the most important practice is to validate the Event notifications for correctness. These validations need to be performed in the enterprise side in the webhook domain where the notifications are received and additionally can be validated in SDC side in the ESS Event Viewer, origin of the notifications. Reconciliating both sources provide certainty on the notification process integrity.

EventViewer option.jpg

This reporting allows you list the events for specific delivery configurations, topic and time range. More information described here.

As an alternative, only as a last/resource - troubleshooting, you could use API calls to programmatically retrieve events data.

This document provides a brief description for ESS API and samples to retrieve Events Notifications information that will provide data useful to validate the webhooks configurations.

For information on how to access this information from the SDC UI click here.

ESS API GET for Events summary

There are 2 methods on the ESS service that can be used to obtain json format data on the Events and the Event Notification.

A GET to https://api.syniverse.com/ess/v1/event-deliveries/summary with the appropriate parameters will retrieve all the occurrence of events described in the subscriptions related to topic and a delivery configuration. As the nature of this data could be of very high volumes the method requires a time period parameter to avoid long time processing to fetch the data.

ESS API GET for an Event Deliveries details

The GET to https://api.syniverse.com/ess/v1/event-deliveries retrieves detailed notification data on specific Event. For this method the delivery configuration id, event id and event timestamp are required to retrieve the event data. This information includes an array of every attempt of sending the event notification to the webhook defined in the subscription.

API call examples

Events summary:

To retrieve the Events for a specific Delivery configuration, in this example for del-cfd-ids 4729 in the period of time from 2023-11-28T14:40:47Z to 2023-11-28T14:46:47Z, you can execute the API call:

curl -L -X GET 'https://api.syniverse.com/ess/v1/event-deliveries/summary?topics=SCG-Message&del-cfg-ids=4729&start-timestamp=2023-11-28T14%3A40%3A47Z&end-timestamp=2023-11-28T14%3A46%3A47Z' \
-H "Authorization: Bearer [token]"

R/
[
{
"event-id": "1FLi3TfWRNiE-Kh7U127bw",
"event-timestamp": "2023-11-28T14:45:44Z",
"topic": "SCG-Message",
"event-type": "message_state_change",
"attempt-no": 3,
"status": "RETRY_PENDING",
"del-cfg-id": 4729,
"del-config-name": "Delivery for DR"
},
{},{}...
]

Event deliveries details:

To retrieve an Event specific information, in this example for del-cfd-ids 4729, the event-id “1FLi3TfWRNiE-Kh7U127bw” with timestamp "2023-11-28T14:45:44Z" as we retrieve in the summary, you can execute the API call:

curl -L -X GET 'https://api.syniverse.com/ess/v1/event-deliveries?del-cfg-id=4729&event-id=1FLi3TfWRNiE-Kh7U127bw&event-timestamp=2023-11-28T14%3A45%3A44Z' \
-H "Authorization: Bearer [token]"

R/
{
"event-id": "1FLi3TfWRNiE-Kh7U127bw",
"event-type": "message_state_change",
"topic": "SCG-Message",
"event-body": "{\"previous_state\":\"SENT\",\"message_request_id\":\"8P9cv0s4M29bVDnQwJzex1\",\"message_id\":\"8P9cv0s4M29bVDnQwJzex1\",\"to_address\":\"+5066173XXXX\",\"has_attachment\":false,\"reason_description\":\"SUCCESS\",\"application_id\":XXXXX,\"reason_code\":\"200\",\"carrier_id\":\"2436\",\"sender_id_alias\":\"FVwXNFWghnXyBazsXXXXXX\",\"company-id\":XXXXXX,\"sender_id_id\":\"FVwXNFWghnXyBazsR1HxQ3\",\"external_message_request_id\":\"\",\"new_state\":\"DELIVERED\",\"fragments_count\":1,\"from_address\":\"7777\",\"carrier_name\":\"MobileNetworkOperator Name\",\"mt_price\":0.0}",
"status": "RETRY_PENDING",
"timestamp": "2023-11-28T14:45:44Z",
"del-cfg-id": 4729,
"addr": "https:// invalid _url.com",
"del-cfg-nm": "Delivery for DR",
"delivery-attempts": [
{
"attempt-number": 1,
"status": "FAILED",
"response-status": 0,
"response-details": "invalid_url.com: Name or service not known",
"attempt-timestamp": "2023-11-28T14:45:45Z"
},
{
"attempt-number": 2,
"status": "FAILED",
"response-status": 0,
"response-details": "[https://invalid_url.com] is blacklisted",
"attempt-timestamp": "2023-11-28T14:46:53Z"
},
{
"attempt-number": 3,
"status": "FAILED",
"response-status": 0,
"response-details": "invalid_url.com: Name or service not known",
"attempt-timestamp": "2023-11-28T14:50:01Z"
}]
}