Webhooks

What are Webhooks?

Think of webhooks as a notification system for your calendar. Instead of constantly checking if something changed, Recal sends you a message the moment an event is created, updated, or deleted.

Real-world use cases:

• Sync calendar events to your CRM in real-time
• Trigger automated workflows when meetings are scheduled
• Update dashboards instantly when availability changes
• Send notifications to your team when events are modified

How It Works

graph LR
    A[Google Calendar] -->|Event Change| B[Recal API]
    B -->|Processes & Formats| C[Your Webhook URL]
    C -->|Receives Clean Event Data| D[Your Application]

    style B fill:#4f46e5,stroke:#4338ca,color:#fff
    style A fill:#4285f4,stroke:#1a73e8,color:#fff

What Recal Handles For You

The beauty of Recal's webhook system is that we handle all the complex Google Calendar API interactions so you don't have to.

Supported Events

Recal sends notifications for three types of calendar events:

{
  "type": "event.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "event": {
    "id": "evt_1234567890",
    "summary": "Team Standup",
    "start": "2024-01-16T09:00:00Z",
    "end": "2024-01-16T09:30:00Z",
    "attendees": ["alice@example.com", "bob@example.com"]
  }
}

{
  "type": "event.updated",
  "timestamp": "2024-01-15T10:30:00Z",
  "event": {
    "id": "evt_1234567890",
    "summary": "Team Standup (Rescheduled)",
    "start": "2024-01-16T14:00:00Z",
    "end": "2024-01-16T14:30:00Z",
    "attendees": ["alice@example.com", "bob@example.com"]
  },
  "changes": ["start", "end", "summary"]
}

{
  "type": "event.deleted",
  "timestamp": "2024-01-15T10:30:00Z",
  "event": {
    "id": "evt_1234567890"
  }
}

Setting Up Webhooks

1. Navigate to Webhooks Settings

In your Recal dashboard, go to Settings → Webhooks (or navigate to /[your-org]/webhooks)

2. Add Your Webhook URL

Click Add Webhook and provide:

• Webhook URL: Your HTTPS endpoint (must use SSL)
• Event Types: Select which events you want to receive

3. Test Your Integration

Once configured, Recal will start sending event notifications to your endpoint. You can view delivery logs and retry failed attempts from the dashboard.

SDK Integration (Coming Soon)

We're building a typesafe SDK handler to make webhook integration even easier:

import { RecalWebhookHandler } from '@recal/sdk'

const handler = new RecalWebhookHandler({
  secret: process.env.RECAL_WEBHOOK_SECRET
})

// TypeScript knows the exact event shape!
handler.on('event.created', (event) => {
  console.log(`New event: ${event.summary}`)
  console.log(`Starts at: ${event.start}`)
})

handler.on('event.updated', (event) => {
  console.log(`Updated fields: ${event.changes.join(', ')}`)
})

handler.on('event.deleted', (event) => {
  console.log(`Deleted event: ${event.id}`)
})

// Express example
app.post('/webhooks/recal', async (req, res) => {
  await handler.handle(req.body, req.headers)
  res.sendStatus(200)
})

Provider Support

Best Practices

Respond Quickly

Your webhook endpoint should respond within 5 seconds. If you need to do heavy processing, acknowledge the webhook immediately and process asynchronously:

app.post('/webhooks/recal', async (req, res) => {
  // Acknowledge immediately
  res.sendStatus(200)

  // Process asynchronously
  processWebhook(req.body).catch(console.error)
})

Handle Idempotency

The same event might be delivered multiple times (e.g., during retries). Use the event ID to ensure you only process each event once:

const processedEvents = new Set()

handler.on('event.created', async (event) => {
  if (processedEvents.has(event.id)) {
    console.log('Already processed, skipping')
    return
  }

  processedEvents.add(event.id)
  await saveToDatabase(event)
})

Verify Signatures (Coming Soon)

When the SDK is released, always verify webhook signatures to ensure requests are genuinely from Recal:

const handler = new RecalWebhookHandler({
  secret: process.env.RECAL_WEBHOOK_SECRET,
  verifySignature: true  // Recommended for production
})

Monitor Delivery Logs

Use the Recal dashboard to monitor webhook deliveries. You can:

• View successful and failed attempts
• See response codes and error messages
• Manually retry failed deliveries
• Debug payload and response data

Security Considerations

1. Use HTTPS Only: Never expose webhook endpoints over HTTP
2. Verify Signatures: Use the SDK's built-in verification (when available)
3. Validate Payloads: Always validate incoming data structure
4. Rate Limit: Implement rate limiting on your endpoint
5. Keep Secrets Safe: Store webhook secrets in environment variables

Troubleshooting

Webhooks Not Arriving

1. Check your webhook URL is accessible from the internet
2. Verify your SSL certificate is valid (test with SSL Labs)
3. Ensure your endpoint returns 2xx status codes
4. Check the delivery logs in the Recal dashboard

Receiving Duplicate Events

This is normal behavior. Implement idempotency using event IDs to handle duplicates gracefully.

What's Next?

• Dashboard Guide - Learn how to manage webhooks in the UI
• API Reference - Interactive API documentation
• OAuth Setup - Connect Google Calendar to receive webhooks