Accepting Webhooks

What are Webhooks?

Webhooks allow ChatToSurvey.com to send real-time notifications to your server when specific events occur in your surveys. Instead of polling our API for updates, you can receive instant notifications about conversations starting, questions being answered, and surveys being completed.

This enables you to integrate ChatToSurvey.com data directly into your CRM, database, or other systems automatically.

Setting Up Webhooks

To receive webhooks, you need to:

1. Create a webhook endpoint in your ChatToSurvey.com dashboard
2. Provide a publicly accessible HTTPS URL where we can send webhook events
3. Select which event types you want to subscribe to
4. Enable the webhook endpoint

Webhook endpoints are managed through the web interface in your dashboard. Navigate to your webhook endpoints page to create and configure endpoints.

Webhook Events

ChatToSurvey.com sends webhooks for the following event types:

Webhook Payload Format

All webhook payloads are sent as JSON in the request body. Each webhook includes:

• id: Unique identifier for the webhook event
• event: The event type (e.g., "conversation.started")
• created_at: ISO 8601 timestamp when the event occurred
• data: Event-specific payload data

{
  "id": "uuid",
  "event": "conversation.started",
  "created_at": "2024-03-06T12:00:00Z",
  "data": {
    "event_type": "conversation.started",
    "survey": {
      "id": "uuid",
      "name": "Customer Feedback Survey",
      "company_id": "uuid"
    },
    "respondent": {
      "id": "uuid",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+1234567890",
      "verified": true
    },
    "conversation": {
      "id": "uuid",
      "channel_type": "embedded_chat",
      "state": "active",
      "started_at": "2024-03-06T12:00:00Z"
    },
    "metadata": {
      "webhook_version": "2.0",
      "delivered_at": "2024-03-06T12:00:00Z"
    }
  }
}

HTTP Headers

Each webhook request includes the following headers:

Content-Type: application/json
User-Agent: HS-Webhook/1.0
X-Webhook-Event: conversation.started
X-Webhook-ID: uuid
X-Webhook-Timestamp: 1709812800

Handling Webhooks

Your webhook endpoint should:

• Return a 200 OK status code within 30 seconds to acknowledge receipt
• Validate the webhook payload structure
• Process the event asynchronously if needed (don't block the response)
• Handle duplicate events idempotently using the webhook ID

If your endpoint doesn't respond with 200 OK within 30 seconds, or returns an error status code, ChatToSurvey.com will retry the webhook delivery up to 5 times with exponential backoff.

Security Considerations

When setting up webhooks:

• Use HTTPS: All webhook URLs must use HTTPS in production
• Validate requests: Verify that requests are coming from ChatToSurvey.com
• Check webhook IDs: Use the webhook ID to prevent processing duplicate events
• Monitor failures: Check your webhook endpoint logs regularly for delivery failures

Example Implementation

Here's a simple example of handling a webhook in a Node.js/Express application:

app.post('/webhooks/chattosurvey', express.json(), (req, res) => {
  const { id, event, created_at, data } = req.body;
  
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process the event asynchronously
  processWebhookEvent({ id, event, created_at, data });
});

async function processWebhookEvent({ id, event, data }) {
  // Check if we've already processed this webhook
  if (await isWebhookProcessed(id)) {
    console.log(`Webhook ${id} already processed`);
    return;
  }
  
  // Process based on event type
  switch (event) {
    case 'conversation.started':
      await handleConversationStarted(data);
      break;
    case 'conversation.completed':
      await handleConversationCompleted(data);
      break;
    case 'question_response.upserted':
      await handleQuestionResponse(data);
      break;
  }
  
  // Mark webhook as processed
  await markWebhookProcessed(id);
}