Monitor Events via Webhook

Yeastar Central Management (YCM) can monitor the system resource and push notifications to a third-party application in real-time via Webhook (an HTTP-based callback mechanism). This topic provides an example on how to monitor YCM events via Webhook.

Webhook workflow

After configuring the Webhook URL and specifying the subscribed events on the Yeastar Central Management, the system will automatically send event details to the third-party application when specified events occur.

Every time the system sends a event notification, the third-party application should return a successful HTTP response (2xx) to acknowledge successful receipt of the message.

Prerequisites

  • You have enabled YCM API.

  • You have obtained a valid Webhook URL from the third-party application.

    In this example, we will use the URL generated by Webhook.site.

Procedure

  1. Log in to the Yeastar Central Management, go to System > API.
  2. Select the checkbox of Webhook Event Push.

  3. Add a Webhook entry and fill in the Webhook information.

    In this example, add a Webhook used to push events to the URL via a POST request when DID numbers assigned to Cloud PBXs are changed.

    Note: Support adding up to 5 Webhooks.

    • Webhook URL: Enter the Webhook URL, which serves as the event push destination.
    • Secret: A system-generated 32-character key used to sign Webhook messages. When sending Webhook events, the system includes the generated signature in the X-Signature header, which can be used to verify the message's authenticity and integrity.
      Tip:
      • After receiving a Webhook request, the recipient can compute an HMAC-SHA256 signature of the received raw message body using the key, Base64-encode the result, and compare it with the signature in the X-Signature header. If the two match, the message is verified as correct and intact.
      • You can click to update it when the key is at risk of being exposed.
    • Request Method: Select the HTTP request method to be either GET or POST, based on the requirements of the third-party Webhook URL.
    • Webhook Event Push: Select the events to monitor.
      Note:
      • Select All if you want to subscribe to all events.
      • For more information about the API events, see Events.
  4. To verify the Webhook configuration, click in Operations to send a test message.

    If the test is successful, the third-party application pointed to by the URL will receive the following message in JSON format: 

    { 
    "event": "test",
    "message": "This is a webhook connectivity test." 
}

    In this example, the Webhook.site received and displayed the test message.

  5. In the Timeout(s) field, set the maximum time to wait for an HTTP response from the third-party application, with a time range of 3-10 seconds.

    If the third-party application does not return a successful HTTP response (2xx) within the specified time, the system will resend the request based on the Retry Count setting.

  6. In the Retry Count drop-down list, select how many times the system should resend the request if delivery fails or no successful response is received.
  7. Click Save.

Result

When a subscribed event occurs, the system automatically sends the event report to the Webhook URL.

In this example, when the DID numbers assigned to a Cloud PBX are updated, the system automatically sends the corresponding event report to the Webhook URL, including the list of current DID information for the Cloud PBX.