Press CTRL+K to open search

Configuring Webhooks for Data Sync

  • 更新日 Oct 22, 2026
  • 公開日 Aug 17, 2021
  • 3 分で読めます
Prev Next
This content is currently unavailable in Ja - 日本語. You are viewing the default (English) version.

Configuring Webhooks for Data Sync

Overview

ScreenMeet webhooks send session events to a URL you control as they happen. Use webhooks to sync session data into a CRM or ticketing system, trigger automation when a session starts or ends, or keep an external record of session activity.

ScreenMeet sends each event as a signed HTTP POST request. Your application verifies the signature with your organization's signing key to confirm the request came from ScreenMeet.

Prerequisites

  • A ScreenMeet console account with the Administrator role.
  • A publicly reachable endpoint that accepts HTTPS POST requests. The URL must start with https://.
  • The ability to read the raw request body on your endpoint before it is parsed.

Step 1: Copy Your Signing Key

  1. Sign in to the ScreenMeet console as an Administrator.
  2. Open the menu and go to Organization > Integration Signing Key.
  3. Click Show, then click Copy.
  4. Store the key as a secret in your application's environment.
Resetting the Signing Key
Reset Signing Key replaces the current key. After a reset, update every application that verifies ScreenMeet signatures with the new key, or those applications will reject incoming webhooks.

Step 2: Create the Webhook

  1. In the ScreenMeet console, go to Organization > Webhooks.
  2. Click New Webhook.
  3. In Webhook URL, enter your endpoint URL.
  4. Optional: click Test next to the URL to send a test request to your endpoint.
  5. In Description, enter a name that identifies the destination system.
  6. Turn on Is Active. Inactive webhooks do not send events.
  7. Click Save Changes.

The webhook now appears in the Organization Webhooks list with its status. Changes can take up to 10 minutes to take effect.

Pausing a Webhook
To stop sending events without deleting the configuration, open the webhook, turn off Is Active, and click Save Changes.

Step 3: Handle Incoming Requests

ScreenMeet sends each webhook request in the following format.

ElementValue
MethodPOST
URLThe Webhook URL you configured.
Content-Type headertext/plain
x-signature headerThe request signature.
x-signature-algo headerThe signing algorithm. Currently sha256.
BodyA JSON array of one or more event objects.

The body is always a JSON array, even when it contains a single event. Iterate over the array and process each event by its type. For field definitions and event types, see the Webhook Data Dictionary.

Why the Content Type Is text/plain
ScreenMeet sends text/plain on purpose. Many web frameworks decode JSON bodies automatically, which changes the bytes and breaks signature verification. Read the raw body as text, verify it, then parse it as JSON.

ScreenMeet can deliver several events in one request, including events that occurred earlier in the session. Use each event's ts field to order events.

Step 4: Verify the Signature

  1. Read the raw request body exactly as received, before any JSON parsing.
  2. Compute a signature over the raw body using your signing key and the algorithm named in x-signature-algo.
  3. Compare your computed value to the x-signature header.
  4. If the values do not match, reject the request and do not process the events.
Always Verify Before Processing
Your webhook URL is reachable from the internet. Process only requests whose signature matches, so your application does not act on forged events.

Detecting When a Session Starts and Ends

To keep an external process in step with a ScreenMeet session, such as holding a chat open while screen sharing is in progress, act on these two events and ignore the rest.

  • session-activated: a participant joined and the session status is now active.
  • session-closed: the session ended. stats.termination-reason and stats.time-ended describe how and when.

Match events to your records using the session id. This is the value after the ? in a Live session link, for example AbCdEfGhIjKl in https://live.screenmeet.com/?AbCdEfGhIjKl.

Closing the Browser Does Not End a Session
A session ends when the agent closes it or when it times out. If the end user closes their browser while the agent is still in the session, the session stays active and session-closed is not sent. Have agents end the session in ScreenMeet when they finish.
Polling Alternative
If your environment cannot accept inbound requests, poll the ScreenMeet API instead. GET /v3/discovery?ids= accepts a comma-separated list of session IDs and returns only the sessions that are currently active. See ScreenMeet API: Poll Session State.

Verification

  1. On the webhook form, click Test and confirm your endpoint receives the request.
  2. Create a test session in the ScreenMeet console. Confirm your endpoint receives a session-created event for that session ID.
  3. Join the session from another browser. Confirm a session-activated event arrives.
  4. End the session. Confirm a session-closed event arrives with status set to closed.
  5. Confirm your signature check passes on each request.