# YMCS 4X Enterprise Open API Webhook.pdf - Pages 1-5

**Source:** YMCS 4X Enterprise Open API Webhook.pdf
**Pages:** 1-5 of 5
**Chunk:** 1

---

YMCS 4X Enterprise Open API Webhook




YMCS 4X Enterprise Open API
Webhook
1. YMCS webhook
1.1 Introduction
Webhook is a user-defined callback API based on HTTP, which you can set up in
your infrastructure to receive change notifications and events from YMCS. To use
the YMCS webhook, users need to fill in a reliable and secure HTTPS webhook
URL on the YMCS platform and subscribe to the events of interest.
1.2 Webhook URL requirements
To receive YMCS event notifications, users need to provide an accessible, HTTPS
secure URL; otherwise, YMCS will not send notifications to the specified URL.
1.3 Receive Event Notification
When the subscribed event occurs, YMCS will send a notification message to the
pre-configured request URL, and the customer application server will receive
and respond to it.
The transmission of notification messages is done using the HTTPS method and
the POST approach. The message format is restricted to JSON format.
Message format
The HTTPS request header information is as follows:

 Heade       description
 r
 conten application/json
 t-type
 conten Content length of the request body (in bytes)
 t-
 length
 author      The verification token returned after successful subscription, used
 izatio      to verify that this request is sent by the YIOT system.
                                                                                   1/5
YMCS 4X Enterprise Open API Webhook



 n
 client      Application ID for configuring event subscriptions
 id
 x-yl-       Requested trace link ID
 reques
 tid

Request Body format example is as follows:

  {
  "events": [
  {
  "id": "6c29f04672b6492ebd0911c2da3414ac",
  "type": "alarm.created",
  "createTime": 1600063609555,
  "partyId": "b986e6eedd6245d697d79da86d6df57c",
  "data": {
  "id": "01d7ae1897f7418dad2d26609329be38",
  "event":"Offline",
  "level":1,
  "mac":"001565bbb1a9",
  "model":"SIP-T54S",
  "ip":"10.50.198.156",
  "site":"test"
  }
  }
  ]
  }


event object

 Paramet       Typ       Description
 er            e
 id            Stri      Event Data Unique Identifier
               ng
 type          Stri      Event Type
               ng
 createT       Lon       Business service generation event time
 ime           g

                                                                  2/5
YMCS 4X Enterprise Open API Webhook



 partyId         Stri       Enterprise ID
                 ng
 userId          Stri       User ID
                 ng
 data            Obje       Event data, format and content determined by the
                 ct         business.

Retry strategy
After receiving the notification request sent by YMCS, the client application
server needs to return a 200 or 204 response within 5s. Once YMCS receives this,
it considers the message delivery successful. If the client application server does
not respond to the notification request within 5s, YMCS will regard this
notification as a failure and will resend the notification request according to the
policy.
The specific retry strategy is to retry after a certain time interval, supporting a
maximum of 3 retries, with specific intervals of: 30s, 5m, 10m. When the retry
period ends and the delivery is still unsuccessful, the message will not be lost; it
will simply not attempt delivery again until new messages arrive for that
subscription. When new messages arrive, undelivered messages within 3 days
will be delivered according to their time.
  During the retry process, if the application server returns a 200 or 204 response within 5s, YMCS considers the
  message delivery successful and will no longer retry.
  Due to network issues or slow event processing, there may be cases of receiving duplicate events. It is
  recommended that the customer's application server perform idempotent processing or deduplication of
  events.

Security policy
YMCS transmits message data via the HTTPS protocol to prevent data from
being tampered with.
The application server needs to validate the received requests by obtaining the
authorization information from the request header. Only when this information
matches the subscription verification token provided by YMCS can it be
confirmed that the request was sent by YMCS.
                                                                                                              3/5
YMCS 4X Enterprise Open API Webhook



The subscription verification token can be obtained in the YMCS event
subscription interface.

2. alarm
2.1 Generate Alarm
Event Type: alarm.created
Event Description: When YMCS receives a device alert, this event notification will
be triggered.
event data

 Parameter                    Type        Description
 id                           String      Alarm ID
 event                        String      Alert event name
 mac                          String      MAC
 model                        String      model

example

  {
  "events": [
  {
  "id": "6c29f04672b6492ebd0911c2da3414ac",
  "type": "alarm.created",
  "createTime": 1600063609555,
  "partyId": "b986e6eedd6245d697d79da86d6df57c",
  "data": {
  "id": "01d7ae1897f7418dad2d26609329be38",
  "event":"Offline",
  "mac":"001565bbb1a9",
  "model":"SIP-T54S"
  }
  }
  ]
  }


2.2 Alarm Recovery
Event type: alarm.recovered

                                                                               4/5
YMCS 4X Enterprise Open API Webhook



Event Description: When the device goes offline and then comes back online,
the status of the registered account for the device changes from failure to
success, which will trigger this event notification.
event data

 Parameter                    Type         Description
 id                           String       Alarm ID
 event                        String       Alert event name
 mac                          String       MAC
 model                        String       Model

example

  {
  "events": [
  {
  "id": "6c29f04672b6492ebd0911c2da3414ac",
  "type": "alarm.recovered",
  "createTime": 1600063609555,
  "partyId": "b986e6eedd6245d697d79da86d6df57c",
  "data": {
  "id": "01d7ae1897f7418dad2d26609329be38",
  "event":"Online",
  "mac":"001565bbb1a9",
  "model":"SIP-T54S",

  }
  }
  ]
  }




                                                                              5/5
