Advanced · 10 min read

Webhooks & Automation

Automate workflows and integrate Sponkly events into your systems using webhooks.

What are Webhooks?

Webhooks allow you to receive real-time notifications when events occur in your Sponkly account. Instead of polling our API, webhooks push data to your endpoint when events happen.

How it works: When an event occurs (e.g., meeting started, translation completed), Sponkly sends an HTTP POST request to your configured endpoint with event details.

Event Types

meeting.created

Triggered when a new meeting room is created

Example Payload
{
  "meeting_id": "mtg_123",
  "created_at": "2025-01-15T10:30:00Z"
}
meeting.started

Triggered when a meeting begins with at least one participant

Example Payload
{
  "meeting_id": "mtg_123",
  "participant_count": 3
}
meeting.ended

Triggered when a meeting ends

Example Payload
{
  "meeting_id": "mtg_123",
  "duration": 1800,
  "ended_at": "2025-01-15T11:00:00Z"
}
translation.completed

Triggered when a translation is completed

Example Payload
{
  "translation_id": "trans_456",
  "source": "en",
  "target": "es"
}
user.joined

Triggered when a user joins a meeting

Example Payload
{
  "user_id": "usr_789",
  "meeting_id": "mtg_123"
}
user.left

Triggered when a user leaves a meeting

Example Payload
{
  "user_id": "usr_789",
  "meeting_id": "mtg_123"
}

Setup Instructions

Step 1: Create an Endpoint

Create an HTTPS endpoint in your application that can receive POST requests.

// Express.js example
app.post('/webhooks/polyspeak', (req, res) => {
  const event = req.body;

  // Verify webhook signature
  const signature = req.headers['x-polyspeak-signature'];
  if (!verifySignature(event, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Handle event
  switch(event.type) {
    case 'meeting.started':
      handleMeetingStarted(event.data);
      break;
    case 'meeting.ended':
      handleMeetingEnded(event.data);
      break;
  }

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

Step 2: Configure Webhook in Dashboard

  1. Go to Settings → Webhooks in your Sponkly dashboard
  2. Click "Add Webhook"
  3. Enter your endpoint URL
  4. Select events you want to subscribe to
  5. Save and copy your webhook secret

Step 3: Verify Webhook Signature

Always verify webhook signatures to ensure requests are from Sponkly.

const crypto = require('crypto');

function verifySignature(payload, signature) {
  const webhookSecret = process.env.POLYSPEAK_WEBHOOK_SECRET;
  const hash = crypto
    .createHmac('sha256', webhookSecret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return hash === signature;
}

Retry Logic

If your endpoint doesn't respond with a 2xx status code, Sponkly will retry the webhook:

  • First retry: 1 minute after failure
  • Second retry: 5 minutes after first retry
  • Third retry: 15 minutes after second retry
  • Fourth retry: 1 hour after third retry
  • Fifth retry: 6 hours after fourth retry

Tip: Respond with 200 OK as quickly as possible, then process the event asynchronously.

Testing Webhooks

Test your webhook integration before going live:

1. Use Webhook Testing Tool

Use our dashboard to send test events to your endpoint and verify responses.

2. Local Testing with ngrok

Use ngrok to expose your local server for webhook testing:

ngrok http 3000

3. Monitor Webhook Logs

Check webhook logs in the dashboard to debug delivery issues.

Best Practices

Always verify webhook signatures to prevent unauthorized requests
Respond with 200 OK immediately, process events asynchronously
Implement idempotency - handle duplicate events gracefully
Use HTTPS endpoints only for security
Store webhook secrets securely (environment variables, secret managers)
Log all webhook events for debugging and auditing
Set reasonable timeouts (we timeout after 30 seconds)
Handle errors gracefully - don't crash on unexpected payloads

Next Steps