How to use webhooks?

Webhooks are HTTP callbacks that VowChat sends to your server when specific events occur in your account. They enable real-time integrations and automation by pushing data to your applications instantly.

What are Webhooks?

Webhooks allow VowChat to send real-time notifications to your application when events happen, such as:

• New message created

• Conversation status changed

• Contact updated

• Agent assigned

• And many more

You can create multiple webhooks per VowChat account, each listening to different events.

How to Set Up Webhooks

Step 1. Go to Settings → Integrations → Webhooks

Step 2. Click the Configure button

Step 3. Click Add new webhook

Step 4. Enter your webhook URL

• This is the endpoint on your server that will receive webhook events

• Must be a publicly accessible HTTPS URL

Step 5. Select the events you want to subscribe to:

• conversation_created

• conversation_updated

• conversation_status_changed

• message_created

• message_updated

• webwidget_triggered

• conversation_typing_on

• conversation_typing_off

Step 6. Click Create to save the webhook

VowChat will now send HTTP POST requests to your URL when subscribed events occur.

Webhook Payload Example

When an event occurs, VowChat sends a JSON payload to your webhook URL.

Message Created Event

{
  "event": "message_created",
  "id": "123",
  "content": "Hi, I need help with my order",
  "created_at": "2024-01-15 10:30:00 UTC",
  "message_type": "incoming",
  "content_type": "text",
  "content_attributes": {},
  "source_id": null,
  "sender": {
    "id": 456,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "conversation": {
    "id": 789,
    "inbox_id": 12,
    "status": "open"
  },
  "account": {
    "id": 11,
    "name": "My Company"
  }
}

Conversation Status Changed Event

{
  "event": "conversation_status_changed",
  "id": 789,
  "status": "resolved",
  "changed_at": "2024-01-15 11:00:00 UTC",
  "conversation": {
    "id": 789,
    "messages": [],
    "contact": {
      "id": 456,
      "name": "John Doe"
    },
    "inbox": {
      "id": 12,
      "name": "Website Chat"
    }
  },
  "account": {
    "id": 11,
    "name": "My Company"
  }
}

Supported Webhook Events

Here are all the events you can subscribe to:

Conversation Events

• conversation_created: New conversation started

• conversation_updated: Conversation details changed

• conversation_status_changed: Status changed (open/resolved/pending)

Message Events

• message_created: New message sent or received

• message_updated: Message edited or updated

Widget Events

• webwidget_triggered: Customer opened the chat widget

Typing Events

• conversation_typing_on: Someone started typing

• conversation_typing_off: Someone stopped typing

Webhook Security

Verify Webhook Signatures

To ensure webhooks are genuinely from VowChat:

1. VowChat includes a signature header in webhook requests

2. Verify the signature on your server

3. Reject requests with invalid signatures

Use HTTPS

• Always use HTTPS URLs for webhook endpoints

• This encrypts data in transit

• Protects sensitive customer information

Handling Webhook Requests

Your webhook endpoint should:

Respond Quickly

• Return a 200 OK response within 5 seconds

• Process webhook data asynchronously if needed

• VowChat will retry failed webhooks

Handle Duplicates

• Webhooks may be sent more than once

• Use the event ID to detect and ignore duplicates

• Implement idempotent processing

Error Handling

• Return appropriate HTTP status codes

• 200-299: Success

• 400-499: Client error (VowChat won't retry)

• 500-599: Server error (VowChat will retry)

Example Server Implementation (Node.js)

const express = require('express');
const app = express();

app.post('/vowchat-webhook', express.json(), (req, res) => {
  const event = req.body;
  
  console.log('Received event:', event.event);
  
  // Process the webhook asynchronously
  processWebhook(event).catch(err => {
    console.error('Webhook processing error:', err);
  });
  
  // Respond immediately
  res.status(200).send('OK');
});

app.listen(3000);

Testing Webhooks

1. Use tools like webhook.site to inspect payloads

2. Create test conversations to trigger events

3. Check your server logs for incoming requests

4. Verify payload structure matches documentation

Common Use Cases

• CRM Integration: Sync conversations to your CRM system

• Analytics: Track conversation metrics in real-time

• Automation: Trigger workflows based on conversation events

• Notifications: Send alerts to Slack, email, or SMS

• Data Warehouse: Archive conversations for analysis

Best Practices

• Subscribe only to needed events: Reduce unnecessary traffic

• Implement retry logic: Handle transient failures gracefully

• Monitor webhook health: Track delivery success rates

• Log webhook data: Keep audit trails for debugging

• Scale your endpoint: Handle high traffic during peak times