Skip to main content
Webhooks allow you to receive real-time notifications when events occur in your G-Tateth account.

​
Overview

Instead of polling the API for changes, webhooks push events to your application in real-time. This is more efficient and provides better user experience.

​
Creating a Webhook

Create a webhook through the API: 
curl -X POST https://api.g-tateth.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "url": "https://myapp.com/webhooks/g-tateth",
    "events": ["conversation.created", "customer.updated"],
    "retryPolicy": {
      "maxRetries": 3,
      "backoffStrategy": "exponential"
    }
  }'
Or use the Developer Console in your dashboard.

​
Supported Events

​
Conversation Events

  • conversation.created - New conversation created
  • conversation.updated - Conversation updated
  • conversation.assigned - Conversation assigned to agent
  • conversation.closed - Conversation closed

​
Customer Events

  • customer.created - New customer created
  • customer.updated - Customer updated

​
Message Events

  • message.sent - Message sent
  • message.received - Message received

​
User Events

  • user.created - New user created
  • user.updated - User updated

​
Call Events

  • call.initiated - Call has been initiated
  • call.ringing - Call is ringing
  • call.answered - Call has been answered
  • call.completed - Call has completed
  • call.failed - Call failed
  • call.recording.available - Call recording is available

​
Webhook Payload

When an event occurs, we’ll send a POST request to your webhook URL: 
{
  "event": "conversation.created",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "_id": "...",
    "subject": "Customer inquiry",
    "status": "open",
    "channel": "email",
    "customerId": {
      "profile": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com"
      }
    }
  }
}

​
Signature Verification

Each webhook request includes an X-Webhook-Signature header for verification. Always verify signatures to ensure requests are from G-Tateth.

​
JavaScript/Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  const expectedSignature = `sha256=${hash}`;
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js example
app.post('/webhooks/g-tateth', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhook(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  // Process event...
  
  res.status(200).send('OK');
});

​
Python

import hmac
import hashlib
import json

def verify_webhook(payload, signature, secret):
    hash = hmac.new(
        secret.encode('utf-8'),
        json.dumps(payload).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    expected_signature = f'sha256={hash}'
    
    return hmac.compare_digest(signature, expected_signature)

# Flask example
@app.route('/webhooks/g-tateth', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    secret = os.environ.get('WEBHOOK_SECRET')
    
    if not verify_webhook(request.json, signature, secret):
        return 'Invalid signature', 401
    
    event = request.json
    # Process event...
    
    return 'OK', 200

​
Retry Policy

Webhooks are automatically retried on failure:
  • Max Retries: Configurable (default: 3)
  • Backoff Strategy: linear or exponential (default: exponential)
  • Exponential: 2s, 4s, 8s, 16s…
  • Linear: 5s, 10s, 15s…

​
Configuring Retry Policy

{
  "name": "My Webhook",
  "url": "https://myapp.com/webhooks",
  "events": ["conversation.created"],
  "retryPolicy": {
    "maxRetries": 5,
    "backoffStrategy": "exponential"
  }
}

​
Testing Webhooks

Test your webhook endpoint: 
curl -X POST https://api.g-tateth.com/api/v1/webhooks/{webhook_id}/test \
  -H "Authorization: Bearer sk_live_your_api_key"
This sends a test event to your webhook URL.

​
Delivery Logs

View webhook delivery history: 
curl https://api.g-tateth.com/api/v1/webhooks/{webhook_id}/logs \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Best Practices

​
1. Always Verify Signatures

Never trust requests without signature verification: 
if (!verifyWebhook(payload, signature, secret)) {
  return res.status(401).send('Invalid signature');
}

​
2. Respond Quickly

Return 200 within 5 seconds. Process events asynchronously: 
app.post('/webhooks/g-tateth', (req, res) => {
  // Acknowledge immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  processWebhookAsync(req.body);
});

​
3. Handle Duplicates

Events may be delivered multiple times. Make handlers idempotent: 
const processedEvents = new Set();

function handleWebhook(event) {
  if (processedEvents.has(event.id)) {
    return; // Already processed
  }
  
  processEvent(event);
  processedEvents.add(event.id);
}

​
4. Use HTTPS

Webhooks must use HTTPS URLs. HTTP is not supported for security reasons.

​
5. Idempotency

Make your webhook handlers idempotent - processing the same event multiple times should have the same effect: 
async function handleConversationCreated(event) {
  const conversationId = event.data._id;
  
  // Check if already processed
  const existing = await db.conversations.findOne({ id: conversationId });
  if (existing) {
    return; // Already processed
  }
  
  // Process event
  await db.conversations.create(event.data);
}

​
Troubleshooting

​
Webhook Not Receiving Events

  1. Check webhook is active
  2. Verify URL is accessible (HTTPS required)
  3. Check delivery logs for errors
  4. Verify signature verification is working

​
Webhook Failing

  1. Check response time (must be < 5 seconds)
  2. Verify endpoint returns 200 status
  3. Check server logs for errors
  4. Review retry policy settings

​
Resources