Webhook

Send recording events to any HTTPS endpoint, with custom payloads, auth headers, and retry handling.

Webhook automations send HTTP requests with recording data to any endpoint when content is added to a folder. This enables custom integrations with internal tools, automation platforms like Zapier, and systems without native Screendesk integrations.

---

When to Use Webhooks

Webhooks are the most flexible automation type. Use them for:

• Custom internal tools — Send data to your own applications

• Automation platforms — Trigger workflows in Zapier, Make (Integromat), or n8n

• Data warehouses — Stream data to analytics platforms

• Incident management — Trigger PagerDuty or Opsgenie alerts

• CRM systems — Update customer records automatically

• Chat platforms — Send to Discord, Teams, or other chat tools

• Logging systems — Forward events to Datadog, Sentry, or LogRocket

Webhooks vs. Native Integrations

Use webhooks when:

• No native integration exists for your tool

• You need custom payload formats

• You're building internal tools

• You want maximum flexibility

Use native integrations (Slack, Linear, Jira) when:

• They exist for your tool

• You want easier setup

• You need OAuth authentication

• You want pre-built formatting

---

Setup

1

Open folder automations

1. Navigate to your folder

2. Click Settings (gear icon)

3. Select Automations tab

4. Click Add Automation

5. Select Webhook

2

Configure webhook endpoint

Webhook URL (required): Enter the destination endpoint:

https://your-app.com/webhooks/screendesk

HTTPS Required

Webhook URLs must use HTTPS (not HTTP). This ensures data is encrypted in transit.

HTTP Method: Choose the request method:

• POST (default) — Standard for webhooks

• PUT — For update-style endpoints

• PATCH — For partial updates

• DELETE — For deletion workflows

Most webhooks use POST.

3

Add authentication headers

Click Add Headers to configure authentication.

Headers are sent as JSON:

{
  "Authorization": "Bearer your-api-token-here",
  "Content-Type": "application/json"
}

Common authentication patterns:

Bearer Token:

{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
}

API Key:

{
  "X-API-Key": "your-api-key-here"
}

Basic Auth:

{
  "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
}

To generate Basic auth, base64 encode username:password.

Webhook Secret (for verification):

{
  "X-Webhook-Secret": "shared-secret-value"
}

4

Configure payload (optional)

By default, Screendesk sends a complete payload with all recording data.

Default payload structure:

{
  "event": "recording.added_to_folder",
  "timestamp": "2026-02-06T15:30:00Z",
  "recording": {
    "id": "rec_abc123",
    "title": "Checkout page crash",
    "url": "https://app.screendesk.io/r/abc123",
    "video_url": "https://cdn.screendesk.io/videos/abc123.mp4",
    "thumbnail_url": "https://cdn.screendesk.io/thumbs/abc123.jpg",
    "customer_email": "[email protected]",
    "duration": 45,
    "browser": "Chrome 121.0",
    "os": "macOS 14.3",
    "console_errors": [...],
    "network_errors": [...],
    "created_at": "2026-02-06T15:30:00Z"
  },
  "folder": {
    "id": "fld_xyz789",
    "name": "Bug Reports"
  },
  "account": {
    "id": "acc_123",
    "name": "Acme Corp"
  }
}

Custom payload:

Enable Custom Payload to define your own structure using template variables:

{
  "type": "bug_report",
  "bug": {
    "title": "{{recording.title}}",
    "reporter": "{{recording.customer_email}}",
    "video_link": "{{recording.url}}",
    "errors": "{{recording.console_errors}}"
  },
  "source": "screendesk",
  "folder": "{{folder.name}}",
  "timestamp": "{{recording.created_at}}"
}

View all template variables →

5

Test the webhook

Click Send Test Webhook to verify your configuration:

1. Screendesk sends a test request to your endpoint

2. Check that your endpoint receives the request

3. Review the response in the test results modal

4. Verify authentication works

5. Confirm payload format is correct

Test results show:

• ✅ Success — HTTP 2xx status code received

• ⚠️ Warning — Non-2xx status with response body

• ❌ Failed — Timeout, connection error, or 4xx/5xx status

View the full request and response in the test results.

6

Save and activate

Once testing succeeds:

1. Click Save to create the automation

2. The automation is enabled by default

3. View it in the folder's Automations tab

The webhook will now fire for every recording added to this folder.

---

Integration Examples

Zapier

Create workflows with 5000+ apps:

1

Create a Zap

1. Go to zapier.com and click Create Zap

2. For the trigger, search for Webhooks by Zapier

3. Choose Catch Hook as the trigger event

4. Copy the provided webhook URL

2

Configure in Screendesk

1. Create a webhook automation in your folder

2. Paste the Zapier webhook URL

3. Leave HTTP method as POST

4. No headers needed

5. Use default payload (Zapier will parse it)

3

Test and continue

1. Click Send Test Webhook in Screendesk

2. Return to Zapier and click Test trigger

3. Zapier should detect the sample data

4. Continue building your Zap with the recording data

---

Slack (via Webhook)

Post to Slack without OAuth:

Webhook URL: Get an incoming webhook URL from Slack:

1. Go to api.slack.com/apps

2. Create an app or select existing

3. Enable Incoming Webhooks

4. Add webhook to channel

5. Copy the webhook URL

Custom Payload:

{
  "text": "🎥 New recording in {{folder.name}}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*{{recording.title}}*\nFrom: {{recording.customer_email}}\nDuration: {{recording.duration}}s"
      }
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {"type": "plain_text", "text": "View Recording"},
          "url": "{{recording.url}}",
          "style": "primary"
        }
      ]
    }
  ]
}

Native Slack Integration

For a simpler setup with more features, use the native Slack integration instead. It provides OAuth authentication, channel selection, and richer formatting options.

---

PagerDuty

Trigger incidents from critical recordings:

Webhook URL:

https://events.pagerduty.com/v2/enqueue

Headers:

{
  "Content-Type": "application/json"
}

Custom Payload:

{
  "routing_key": "YOUR_INTEGRATION_KEY_HERE",
  "event_action": "trigger",
  "payload": {
    "summary": "Critical: {{recording.title}}",
    "severity": "critical",
    "source": "Screendesk",
    "custom_details": {
      "recording_url": "{{recording.url}}",
      "customer": "{{recording.customer_email}}",
      "console_errors": "{{recording.console_errors}}",
      "browser": "{{recording.browser}}"
    }
  },
  "links": [
    {
      "href": "{{recording.url}}",
      "text": "View Recording"
    }
  ]
}

Get your integration key from PagerDuty → Services → Integrations → Events API V2.

---

Discord

Post to Discord channels:

Webhook URL: Get from Discord:

1. Open channel settings

2. Go to Integrations → Webhooks

3. Create webhook

4. Copy URL

Custom Payload:

{
  "content": "🎥 **New Recording**",
  "embeds": [
    {
      "title": "{{recording.title}}",
      "description": "From: {{recording.customer_email}}\nDuration: {{recording.duration}} seconds",
      "url": "{{recording.url}}",
      "color": 15258703,
      "fields": [
        {
          "name": "Browser",
          "value": "{{recording.browser}}",
          "inline": true
        },
        {
          "name": "OS",
          "value": "{{recording.os}}",
          "inline": true
        }
      ]
    }
  ]
}

---

Microsoft Teams

Post to Teams channels:

Webhook URL: Get from Teams:

1. Open channel

2. Click ⋯ (More options)

3. Connectors → Incoming Webhook

4. Configure and copy URL

Custom Payload:

{
  "@type": "MessageCard",
  "@context": "https://schema.org/extensions",
  "summary": "New Recording",
  "themeColor": "E91E63",
  "title": "🎥 {{recording.title}}",
  "sections": [
    {
      "facts": [
        {"name": "Customer", "value": "{{recording.customer_email}}"},
        {"name": "Duration", "value": "{{recording.duration}}s"},
        {"name": "Browser", "value": "{{recording.browser}}"}
      ]
    }
  ],
  "potentialAction": [
    {
      "@type": "OpenUri",
      "name": "View Recording",
      "targets": [
        {"os": "default", "uri": "{{recording.url}}"}
      ]
    }
  ]
}

---

Webhook Security

Verify webhook signatures

Screendesk signs all webhooks with HMAC-SHA256. Verify requests are legitimate:

Signature header:

X-Screendesk-Signature: sha256=abc123...

Verification (Node.js):

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  const expected = `sha256=${expectedSignature}`;

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Usage
const isValid = verifyWebhook(
  req.body,
  req.headers['x-screendesk-signature'],
  'your-webhook-secret'
);

Verification (Python):

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    expected_signature = f"sha256={expected}"

    return hmac.compare_digest(signature, expected_signature)

Always Verify Signatures

Without verification, anyone who knows your webhook URL can send fake requests. Always verify the X-Screendesk-Signature header in production.

---

Retry Policy

Failed webhooks are automatically retried with exponential backoff:

Attempt	Delay	Total Time
Initial	—	0s
1st retry	1 minute	1m
2nd retry	5 minutes	6m
3rd retry	30 minutes	36m
4th retry	2 hours	2h 36m
5th retry	12 hours	14h 36m

After 5 failed attempts, the webhook is marked as permanently failed.

Success criteria:

• HTTP status code 2xx (200-299)

• Response received within 30 seconds

Your endpoint should:

• Respond with 2xx as quickly as possible

• Process webhooks asynchronously if needed

• Be idempotent (handle duplicate deliveries)

• Return within 30 seconds

---

Troubleshooting

Connection errors

Symptom: "Failed to connect" or timeout errors

Solutions:

• Verify URL is correct and publicly accessible

• Ensure endpoint uses HTTPS (not HTTP)

• Check firewall allows Screendesk IPs

• Confirm endpoint responds within 30 seconds

• Test endpoint with curl:

  curl -X POST https://your-endpoint.com/webhook \
    -H "Content-Type: application/json" \
    -d '{"test": true}'

---

Authentication errors

Symptom: 401 Unauthorized or 403 Forbidden

Solutions:

• Verify API keys or tokens are correct

• Check header names match exactly (case-sensitive)

• Ensure tokens haven't expired

• Confirm permissions allow webhook access

• Test with a tool like Postman first

---

Invalid payload

Symptom: 400 Bad Request with validation errors

Solutions:

• Validate JSON syntax in custom payload

• Check template variables are spelled correctly

• Ensure required fields are present

• Test payload structure with the endpoint's documentation

• Use default payload first, then customize

---

Timeout errors

Symptom: "Request timed out after 30 seconds"

Solutions:

• Optimize endpoint to respond faster

• Return 2xx immediately, process asynchronously

• Reduce database queries or external API calls

• Cache data when possible

• Check for infinite loops or blocking operations

---

View execution logs

Check webhook delivery history:

1. Open folder Settings → Automations

2. Click the webhook automation

3. View Execution Log tab

Logs show:

• Timestamp

• HTTP status code

• Request payload sent

• Response body received

• Error messages

• Retry attempts

---

Best Practices

Respond quickly

Return 2xx status as fast as possible:

❌ Don't do this:

app.post('/webhook', (req, res) => {
  // Process synchronously (slow)
  processRecording(req.body);
  sendNotifications(req.body);
  updateDatabase(req.body);

  res.status(200).send('OK');
});

✅ Do this:

app.post('/webhook', (req, res) => {
  // Respond immediately
  res.status(200).send('OK');

  // Process asynchronously
  queue.add('process-webhook', req.body);
});

---

Make endpoints idempotent

Handle duplicate deliveries gracefully:

app.post('/webhook', async (req, res) => {
  const recordingId = req.body.recording.id;

  // Check if already processed
  const exists = await db.webhooks.findOne({ recordingId });
  if (exists) {
    return res.status(200).send('Already processed');
  }

  // Process and store
  await processWebhook(req.body);
  await db.webhooks.insert({ recordingId, processedAt: new Date() });

  res.status(200).send('OK');
});

---

Log webhook requests

Keep logs for debugging:

• Log all incoming webhook requests

• Store request body and headers

• Track processing status

• Keep logs for at least 30 days

• Alert on high failure rates

---

Monitor and alert

Set up monitoring for:

• Webhook failure rate > 5%

• Response time > 10 seconds

• Missing webhooks (check counts)

• Authentication failures

• Endpoint downtime

Use your logging platform or APM tool to track these metrics.

---

Test thoroughly

Before going live:

• Test with the Send Test Webhook button

• Verify all data fields are present

• Check template variables populate correctly

• Confirm authentication works

• Test with your full processing pipeline

• Verify retries work as expected