Webhooks

Webhook-urile va permit sa primiti notificari in timp real cand se intampla evenimente in widget-ul dvs. de chat. Cand un vizitator incepe un chat, trimite un formular sau trimite un mesaj, Chatim trimite o cerere HTTP POST la URL-ul dvs. cu datele evenimentului.

Prezentare generala

Cu webhook-urile puteti:

• Trimite automat noi leaduri catre CRM-ul dvs.
• Declansa fluxuri de lucru in Zapier, Make sau aplicatii personalizate
• Inregistra evenimente de chat in platforma dvs. de analiza
• Notifica echipa in Slack sau alte instrumente
• Sincroniza datele vizitatorilor cu baza dvs. de date

Accesarea Webhook-urilor

1. Conectati-va la panoul de control Chatim
2. Selectati proiectul din bara laterala
3. Faceti clic pe Webhooks in meniul de navigare

Crearea unui Webhook

1. Faceti clic pe Creare Webhook
2. Introduceti un Nume optional (ex., "Integrare CRM")
3. Introduceti URL-ul unde trebuie trimise evenimentele
4. Selectati unul sau mai multe Evenimente pe care doriti sa le primiti
5. Faceti clic pe Creare

Dupa creare, veti vedea un Secret Webhook - copiati-l si salvati-l imediat. Acest secret este folosit pentru a verifica ca cererile primite provin de la Chatim. Este afisat doar o singura data.

Evenimente suportate

Sarcina utila a Webhook-ului

Fiecare livrare de webhook este o cerere HTTP POST cu un corp JSON.

Campuri comune

{
  "event": "chat.started",
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "projectUuid": "your-project-uuid",
  "chatUuid": "visitor-chat-uuid",
  "data": { }
}

chat.started

Include informatii despre vizitator, URL-ul paginii, locatia si agentul utilizator.

{
  "event": "chat.started",
  "data": {
    "visitor": {
      "uuid": "visitor-uuid",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890"
    },
    "page": {
      "url": "https://example.com/pricing",
      "title": "Pricing - Example"
    },
    "location": { "country": "US", "city": "Los Angeles" },
    "userAgent": { "browser": "Chrome", "os": "Windows", "device": "Desktop" }
  }
}

chat.message.received

{
  "event": "chat.message.received",
  "data": {
    "messageUuid": "message-uuid",
    "message": "Hi, I have a question about your pricing.",
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.form.submitted

{
  "event": "chat.form.submitted",
  "data": {
    "formNodeId": "node-id",
    "formName": "Contact Form",
    "fields": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "message": "I'd like a product demo."
    },
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.closed

Include cine a inchis chatul (agent, visitor, system sau timeout), durata in secunde, numarul de mesaje si transcriptia.

{
  "event": "chat.closed",
  "data": {
    "closedBy": "agent",
    "status": "closed",
    "duration": 345,
    "messageCount": 12,
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.assigned

Trimis cand un agent de suport se alatura conversatiei.

{
  "event": "chat.assigned",
  "data": {
    "assignedTo": { "uuid": "agent-uuid", "name": "Jane Smith" },
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

chat.handoff

Trimis cand chatbotul face tranzitia la modul de chat live.

{
  "event": "chat.handoff",
  "data": {
    "reason": "Visitor requested human support",
    "fromNode": "node-id",
    "visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
  }
}

Securitate

Verificarea semnaturii

Fiecare cerere webhook include o semnatura pentru a putea verifica ca provine de la Chatim. Semnatura este calculata ca HMAC-SHA256(secret, timestamp + "." + payload) si trimisa in headerul X-Chatim-Signature.

Headere de cerere

Exemplu de verificare Node.js

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-chatim-signature'];
  const timestamp = req.headers['x-chatim-timestamp'];
  const body = JSON.stringify(req.body);

  // Reject requests older than 5 minutes
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Exemplu de verificare Python

import hmac, hashlib, time

def verify_webhook(headers, body, secret):
    signature = headers.get('X-Chatim-Signature', '')
    timestamp = headers.get('X-Chatim-Timestamp', '')

    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = 'sha256=' + hmac.new(
        secret.encode(),
        f'{timestamp}.{body}'.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Logica de reincercare

Daca endpoint-ul dvs. nu este disponibil sau returneaza o eroare, Chatim reincearca automat.

Dupa 5 reincercari esuate, livrarea este marcata ca esuata. Raspunsurile 2xx sunt tratate ca succes, 4xx ca esecuri permanente (fara reincercare), 5xx si timeout-urile (30s) declanseaza reincercari.

Daca un webhook acumuleaza 10 esecuri consecutive, este dezactivat automat. Il puteti reactiva din panoul de control dupa rezolvarea problemei.

Administrarea Webhook-urilor

Testare

Faceti clic pe Testare pe orice webhook pentru a trimite un eveniment exemplu chat.started la URL-ul dvs. Aceasta va permite sa verificati endpoint-ul inainte de a merge in productie.

Istoricul livrarilor

Faceti clic pe un webhook pentru a vedea livrarile recente cu tipul evenimentului, marca de timp, codul de stare HTTP si mesajele de eroare. Istoricul este pastrat timp de 30 de zile.

Regenerarea unui secret

Daca secretul webhook-ului este compromis, faceti clic pe Regenerare secret, salvati noul secret si actualizati endpoint-ul. Secretul vechi este invalidat imediat.

Cazuri de utilizare

Integrare CRM

Abonati-va la chat.form.submitted si chat.started pentru a crea automat contacte si leaduri in CRM-ul dvs.

Notificari Slack

Abonati-va la chat.assigned si chat.handoff pentru a alerta echipa cand un vizitator are nevoie de suport live.

Analiza

Abonati-va la toate evenimentele pentru a construi o imagine completa a angajamentului in chat, ratelor de conversie a formularelor si timpilor de raspuns al suportului.

Automatizare email

Abonati-va la chat.form.submitted pentru a declansa emailuri de bun venit, secvente de urmarire sau mesaje de confirmare.

Cele mai bune practici

• Returnati un raspuns 2xx rapid - procesati datele asincron
• Folositi HTTPS pentru URL-ul endpoint-ului
• Verificati intotdeauna semnatura webhook-ului inainte de procesare
• Implementati idempotenta folosind eventId pentru a gestiona livrarile duplicate
• Stocati secretul webhook-ului in siguranta (variabila de mediu, manager de secrete)
• Validati marca de timp pentru a preveni atacurile de reluare (respingeti cererile mai vechi de 5 minute)

Depanare

Webhook-ul nu primeste evenimente

1. Verificati ca webhook-ul este Activ (nu dezactivat)
2. Verificati ca URL-ul este corect si accesibil public
3. Folositi butonul Testare pentru a trimite un eveniment exemplu
4. Verificati jurnalele serverului pentru cereri primite
5. Asigurati-va ca endpoint-ul returneaza un cod de stare 2xx

Webhook dezactivat automat

1. Verificati motivul dezactivarii in panoul de control
2. Rezolvati problema de baza (endpoint cazut, returnand erori)
3. Faceti clic pe Activare pentru a reactiva
4. Folositi Testare pentru a verifica inainte de reactivare

Verificarea semnaturii esueaza

1. Asigurati-va ca folositi secretul corect
2. Verificati ca semnati timestamp + "." + raw_body (nu JSON parsat)
3. Folositi comparatie sigura in timp pentru a preveni atacurile temporale