Webhook

Documentation for the webhook integration mechanism with supported platforms.

Currently supported:

  • Zapier
  • Make

Authentication

All incoming webhook requests must include the x-screenreply-token header with your backend token.

To obtain your token, navigate to the ScreenReply dashboard, find the specific integration card (e.g. Zapier), and click the Setup button. 

x-screenreply-token: YOUR_BACKEND_TOKEN

Endpoint

All actions are sent via a single POST endpoint. The endpoint URL always remains the same; however, the JSON payload structure changes depending on the specific operation being executed (determined by the action field).

POSThttps://api.screenreply.com/public/webhooks/{provider}

Path Parameters

ParameterTypeDescription
provider*StringReplace {provider} with the uppercase name of the supported integration (e.g., ZAPIER).

Common Error Responses

The following errors can occur with any action. Each error returns a JSON body with a message field describing the issue.

StatusConditionResponse Body
400Provider not found in the URL path (e.g. ZAPIER vs ZAPIER2).{"message": "Bad request"}
400Request body is malformed or missing the action field.{"message": "Bad request"}
403The x-screenreply-token value does not match the stored backend token.{"message": "Forbidden"}
424No active integration found. The token is missing, expired, or the integration was disconnected.{"message": "Integration error"}

1. Ping (Check Auth)

Verify that your integration is properly configured and authenticated.

Request Body (application/json)

FieldTypeDescription
action*StringMust be "PING".

Example Request

curl -X POST https://api.screenreply.com/public/webhooks/ZAPIER   -H "x-screenreply-token: YOUR_BACKEND_TOKEN"   -H "Content-Type: application/json"   -d '{
    "action": "PING"
  }'

Response 200 OK

FieldTypeDescription
statusStringReturns "success" if the credentials and workspace are valid.
workspaceStringReturns the name of the workspace.
{
  "status": "success",
  "workspace": "KinetiSend Inc"
}

Error Responses

StatusConditionResponse Body
400The integration was disconnected or no longer exists.{"message": "Bad request"}

2. Create Recording Action

Request a new screen recording. The response contains a shareable link to send to the recording participant.

Request Body (application/json)

FieldTypeDescription
action*StringMust be "RECORDING".
recording*ObjectA wrapper object containing recording parameters.
recording.tagsArray of StringsOptional. A list of string labels to attach to the video (e.g. ["bug", "ui"]).
recording.externalReference*StringRequired. The unique identifier from your system (e.g., an executionId, taskId, or ticketId) to associate with this recording.

Example Request

curl -X POST https://api.screenreply.com/public/webhooks/ZAPIER   -H "x-screenreply-token: YOUR_BACKEND_TOKEN"   -H "Content-Type: application/json"   -d '{
    "action": "RECORDING",
    "recording": {
      "tags": ["bug", "ui"],
      "externalReference": "ext-123"
    }
  }'

Response 200 OK

FieldTypeDescription
urlStringThe fully qualified URL of the created recording page.
{
  "url": "https://rec.screenreply.com/r/3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Error Responses

These errors return 200 OK with an error field in the body.

StatusConditionResponse Body
200Workspace subscription is expired or canceled.{"error": "No active subscription."}
200Integration token is invalid or the integration was disconnected.{"error": "Integration not connected."}
200Unexpected server error.{"error": "Internal Server Error"}

3. Subscribe to Video Ready Events (REST Hook)

Register a callback URL to receive a POST request when a recording is ready. ScreenReply will send the video link to the exact URL you provide.

Request Body (application/json)

FieldTypeDescription
action*StringMust be "CALLBACK_SUBSCRIBE".
callback*StringThe fully qualified HTTPS URL of your application's endpoint that will receive the video links.

Example Request

curl -X POST https://api.screenreply.com/public/webhooks/ZAPIER   -H "x-screenreply-token: YOUR_BACKEND_TOKEN"   -H "Content-Type: application/json"   -d '{
    "action": "CALLBACK_SUBSCRIBE",
    "callback": "https://your-app.com/webhook"
  }'

Response 200 OK

FieldTypeDescription
subscriptionIdString (UUID)A UUID generated by ScreenReply that uniquely identifies this webhook subscription. Save this ID to unsubscribe later.
{
  "subscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Error Responses

These errors return 200 OK with an error field in the body.

StatusConditionResponse Body
200Workspace subscription is expired or canceled.{"error": "No active subscription."}
200Unexpected server error (e.g., integration was disconnected).{"error": "Internal Server Error"}

4. Unsubscribe from Events

Remove a previously registered callback subscription using its ID.

Request Body (application/json)

FieldTypeDescription
action*StringMust be "CALLBACK_UNSUBSCRIBE".
subscriptionId*String (UUID)The UUID of the subscription you wish to remove.

Example Request

curl -X POST https://api.screenreply.com/public/webhooks/ZAPIER   -H "x-screenreply-token: YOUR_BACKEND_TOKEN"   -H "Content-Type: application/json"   -d '{
    "action": "CALLBACK_UNSUBSCRIBE",
    "subscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

Response 200 OK

FieldTypeDescription
statusStringReturns "success" when the subscription is deleted.
{
  "status": "success"
}

Error Responses

These errors return 200 OK with an error field in the body.

StatusConditionResponse Body
200Invalid subscriptionId or unexpected server error.{"error": "Internal Server Error"}

Outgoing Notification (ScreenReply → Your App)

When a recording is finished, ScreenReply will send a POST request containing the video link to the exact callback URL that was registered during the CALLBACK_SUBSCRIBE step.

Payload Schema

FieldTypeDescription
resultStringThe raw, fully qualified HTTPS link to the video.
{
  "result": "https://app.screenreply.com/r/3fa85f64-5717-4562-b3fc-2c963f66afa6"
}