Webhook-uri #

Webhook-urile permit Your AI Connector să notifice automat celelalte instrumente de afaceri ori de câte ori se întâmplă ceva important — crearea unui contact nou, programarea unei întâlniri, primirea unui mesaj. În loc să verificați manual actualizările, sistemele conectate primesc o notificare instantanee în momentul în care are loc un eveniment.

Ce sunt webhook-urile? #

Gândiți-vă la un webhook ca la un mesaj text automat între două aplicații. Când se întâmplă ceva în Your AI Connector (cum ar fi înregistrarea unui contact nou), platforma trimite instantaneu o notificare către un alt sistem ales de dumneavoastră. Furnizați o adresă web (numită „URL webhook”) unde ar trebui trimise aceste notificări — aceasta este furnizată de obicei de CRM-ul, platforma de automatizare sau dezvoltatorul dumneavoastră.

Webhook-urile trimit date DOAR în afara Your AI Connector. Un webhook este o cale cu sens unic de la Your AI Connector către celelalte instrumente ale tale. Nu există niciun URL de webhook care să trimită clienți potențiali, contacte sau mesaje ÎN platformă. Pentru a introduce un client potențial nou — dintr-un formular de pe site, din CRM-ul tău sau din GoHighLevel — sistemul tău efectuează în schimb un apel API. Consultă Acces API (operațiunea Create a Contact) și Funnel-uri. Singurul lucru de care ai nevoie pentru direcția de intrare este cheia API, care se află în propria sa secțiune — consultă Acces API. Pagina Webhook-uri descrisă aici este exclusiv pentru direcția de ieșire.

Utilizările comune includ:

• Sincronizarea contactelor noi cu CRM-ul dumneavoastră.
• Declanșarea unui flux de lucru în Zapier, Make sau Pabbly atunci când este aplicată o etichetă.
• Notificarea echipei în Slack atunci când un om este alertat.
• Actualizarea sistemului de calendar atunci când este programată o întâlnire.
• Înregistrarea rezumatelor conversațiilor în baza de date.

Configurarea webhook-urilor #

1. În bara laterală din stânga, faceți clic pe Settings (pictograma roată).
2. În bara laterală Settings, sub grupul Integrations, faceți clic pe Webhooks.

Într-un cont în care nu sunt configurate încă webhook-uri, pagina arată astfel:

3. Faceți clic pe New webhook (Webhook nou), în dreapta sus. Un formular se va deschide direct în pagină:

4. Completați:
   • URL Endpoint — adresa web către care Your AI Connector va trimite notificările despre evenimente. O obțineți de la sistemul extern (CRM, platformă de automatizare sau server personalizat).
   • Nume — o etichetă pe care o veți recunoaște ulterior (de exemplu, „Alerte Slack” sau „Sincronizare CRM”). Doar pentru referința dumneavoastră.

URL-ul dvs. de webhook trebuie să fie o adresă https:// accesibilă public. Adresele http:// simple, localhost sau adresele de rețea privată și adresele interne ale platformei sunt respinse la salvare. Pentru a testa de pe propriul computer, utilizați un tunel public (webhook.site sau ngrok) în loc de localhost.

5. Sub Evenimente, faceți clic pe evenimentele pe care doriți să le primească acest webhook — toate cele 22 sunt listate în Cele 22 de evenimente Webhook.
6. (Opțional) Activați Reîncercare livrări eșuate dacă doriți ca Your AI Connector să continue să încerce în caz de eșec temporar — consultați Reîncercarea livrărilor eșuate.
7. Faceți clic pe Creează webhook. Acesta apare în lista de sub formular și puteți face clic pe Test în rândul său oricând pentru a trimite un payload de probă către endpoint-ul dvs.

Permisiune necesară. Adăugarea, editarea sau testarea webhook-urilor necesită permisiunea „edit” pentru Integrations (membrii echipei cu acces doar pentru vizualizare vor vedea o notificare de tip read-only în locul formularului).

Semnarea unui webhook necesită ca acesta să fie deja salvat — deschideți rândul unui webhook existent pentru a-l edita, iar panoul Signing secret va apărea în partea de jos a formularului de editare. O schiță nouă, nesalvată, nu are încă opțiune de semnare — consultați Signed Payloads mai jos.

Un singur webhook pentru toate conturile clienților tăi (Agenții) #

Dacă administrezi o agenție, nu trebuie să recreezi același webhook pentru fiecare cont de client. În contul de agenție, formularul pentru webhook are un comutator suplimentar: Also fire for all client accounts. Activează-l și acest webhook va primi și evenimentele care au loc în fiecare cont de client din cadrul agenției tale — un singur endpoint pentru întreaga agenție.

Cum funcționează:

• Blocul user îți indică apartenența evenimentului la un anumit client. Fiecare notificare conține deja un bloc user care identifică contul în care a avut loc evenimentul, astfel încât automatizarea ta să poată direcționa datele per client.
• Setările proprii ale webhook-ului tău se aplică peste tot. Evenimentele selectate, secretul de semnare și setarea de reîncercare sunt utilizate și pentru livrările către conturile clienților.
• Fără livrări duble. Dacă un cont de client are propriul său webhook care indică către același URL, acesta va fi utilizat în schimb pentru evenimentele acelui cont — același eveniment nu va ajunge niciodată de două ori la același endpoint.
• Clienții nu îl văd. Webhook-ul nu apare în pagina de Webhooks a contului clientului, iar clienții nu îl pot dezactiva — este sub controlul tău.
• Fiabilitatea este monitorizată per cont de client. Dacă endpoint-ul tău continuă să eșueze, acesta este dezactivat automat doar pentru contul ale cărui livrări au eșuat (vezi Fiabilitatea Webhook-urilor), nu pentru întreaga agenție deodată.

Comutatorul apare doar în conturile de agenție. Configurarea acestuia prin API este, de asemenea, acceptată — vezi câmpul apply_to_sub_accounts din Webhooks API.

Evenimente de declanșare disponibile #

Puteți activa sau dezactiva fiecare dintre cele 22 de evenimente webhook în mod independent. Când un eveniment este declanșat, Your AI Connector trimite o notificare către URL-ul webhook-ului dvs. cu datele relevante. Fiecare eveniment, semnificația acestuia și codul event pe care îl introduce în payload sunt listate împreună în Cele 22 de evenimente Webhook mai jos pe această pagină.

Bine de știut: Task Created, Task Updated și Task Completed sunt complet selectabile și se salvează corect. Daily Summary Created este, de asemenea, o adăugare recentă. Consultați Webhook pentru Task Completed mai jos pentru structura acelui payload.

Declanșatoare de webhook bazate pe etichete #

subscribed_to_tags nu limitează evenimentele unui webhook la o etichetă. Acesta doar restrânge etichetele care produc o notificare de rezumat al conversației. Pentru a primi o solicitare atunci când este aplicată o anumită etichetă, setați un URL de webhook pe acea etichetă în fila Etichete a agentului (sau campaniei).

Formularul de webhook în sine nu are un selector de etichete, nici la crearea unui webhook nou, nici la editarea unuia, deci subscribed_to_tags poate fi citit sau modificat doar prin API-ul Webhooks sau solicitând asistență.

Bine de știut: editarea unui webhook existent care are o listă subscribed_to_tags (redenumirea acestuia, modificarea evenimentelor, activarea reîncercărilor) nu mai șterge acea listă — deoarece formularul nu are un selector de etichete de trimis înapoi, salvarea din această pagină lasă acum lista existentă neatinsă. (Aceasta a fost o eroare reală înainte de 21 iulie 2026: salvarea din formularul de webhook obișnuia să șteargă lista deoarece trimitea întotdeauna o listă de etichete goală. Dacă un webhook și-a pierdut lista subscribed_to_tags înainte de acea dată, va trebui reconfigurat prin API.)

Generarea unui rezumat pentru contactele etichetate #

Acolo unde un webhook are o listă subscribed_to_tags, puteți activa Generează rezumat. Când este activat, Your AI Connector generează automat un rezumat al conversației pentru contact atunci când una dintre acele etichete este aplicată și îl include în datele webhook-ului — context complet fără o solicitare separată.

Testarea webhook-ului dumneavoastră #

1. Deschideți Setări → Integrări → Webhook-uri.
2. Pe rândul webhook-ului dvs., faceți clic pe Test.
3. Verificați sistemul extern pentru a confirma că a primit datele de test.
4. Examinați formatul datelor pentru a vă asigura că sistemul dvs. îl poate analiza corect.

Pentru un test complet cap-la-cap, trimiteți un mesaj care ar declanșa unul dintre evenimentele configurate (o difuzare sau un mesaj primit pe un canal conectat) și verificați dacă webhook-ul se declanșează cu datele reale.

Ce este considerată o livrare reușită #

Indiferent dacă dai clic pe Test sau dacă evenimentul este declanșat în mod real, trimitem același lucru:

• O solicitare POST (niciodată GET), cu corpul sub formă de JSON și Content-Type: application/json.
• Antetele listate sub Payload-uri semnate. Antetele de semnătură sunt incluse doar după ce ați setat o cheie secretă de semnare.

Considerăm livrarea reușită atunci când:

• Endpoint-ul tău răspunde cu orice cod de stare 2xx (200, 201, 204 — toate sunt acceptate).
• Răspunde în decurs de 30 de secunde.

Câteva aspecte care îi surprind pe utilizatori:

• Corpul răspunsului este ignorat. Nu trebuie să returnați niciun JSON anume. Un răspuns 200 gol este suficient.
• Redirecționările sunt considerate eșecuri. Noi nu le urmăm, așa că un cod 301 sau 302 (inclusiv o redirecționare cu slash la final sau de la http la https) este înregistrat ca o livrare eșuată. Salvați URL-ul final, nu unul care redirecționează.
• Șirurile de interogare (query strings) sunt pe deplin acceptate. https://your-app.com/hook?token=abc123 este trimis exact așa cum l-ați salvat, deci plasarea unui token în șirul de interogare funcționează la fel de bine ca plasarea lui în cale.
• URL-ul dumneavoastră trebuie să fie https:// și accesibil public. Adresele care aparțin propriei infrastructuri Your AI Connector sunt respinse, dar propriile dumneavoastră endpoint-uri pe Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting sau oriunde altundeva sunt în regulă.
• Un firewall sau un strat de protecție împotriva boților din fața endpoint-ului dumneavoastră ne poate bloca. Cel mai frecvent caz este Cloudflare: dacă zona dumneavoastră are activat „Bot Fight Mode” sau o provocare gestionată, cererea noastră primește o pagină de provocare „Just a moment…” cu un cod 403 în loc să ajungă la serverul dumneavoastră — iar o cerere server-la-server nu poate trece niciodată de o provocare de browser, așa că atât butonul Test, cât și evenimentele reale eșuează în același mod. Butonul Test vă va spune când se întâmplă acest lucru („Cloudflare is showing a bot challenge to our request”). Remediați problema în Cloudflare cu o regulă de Securitate / WAF care omite provocările pentru calea webhook-ului dumneavoastră (sau pentru agentul utilizator Webhook-Delivery/1.0), apoi faceți clic din nou pe Test.
• Dacă firewall-ul dumneavoastră are nevoie de o listă de permisiuni IP în schimb (de exemplu, planul gratuit Cloudflare, unde „Bot Fight Mode” simplu nu poate fi omis printr-o regulă WAF, dar o regulă de acces IP setată pe „Allow” rulează înaintea acestuia), vă putem ajuta: fiecare livrare, fie că provine de la butonul Test sau de la un eveniment live, este trimisă de la o singură adresă IPv4 fixă (fără intervale, fără IPv6, fără rotație). Contactați asistența și vă vom oferi adresa pentru a o adăuga în lista de permisiuni. Păstrați verificarea semnăturii ca verificare reală de încredere, deoarece aceasta validează fiecare sarcină utilă indiferent de locul din care provine.
• Rezultatul testului vă spune exact ce a răspuns endpoint-ul dumneavoastră. Un test eșuat arată acum motivul real (codul de stare HTTP pe care l-a returnat endpoint-ul dumneavoastră, un timeout sau faptul că nu am putut accesa deloc adresa) în loc de o eroare generică, iar un test pe un webhook salvat este trimis semnat atunci când semnarea este activată, exact ca un eveniment live.

Utilizarea n8n, Make sau Zapier (“Test URL” vs “Production URL”) #

Platformele de automatizare îți oferă de obicei două adrese webhook diferite, iar acest lucru îi induce pe mulți în eroare:

• Un URL de test (în n8n conține /webhook-test/). Acesta primește date doar în timp ce monitorizați activ panoul și tocmai ați făcut clic pe Ascultă evenimentul de test (sau Testare flux de lucru). Acesta captează un singur eveniment și apoi încetează să mai asculte — deci, dacă faceți clic pe Test în Your AI Connector de mai multe ori la rând, se va capta doar primul, și doar dacă fereastra de ascultare este activă în acel moment exact. Pentru a testa: faceți clic mai întâi pe Ascultă evenimentul de test în n8n, apoi reveniți la Your AI Connector și faceți clic pe Test o singură dată.
• Un URL de producție (în n8n conține /webhook/, fără -test). Acesta este cel care trebuie lipit în Your AI Connector pentru evenimente live. Funcționează doar după ce fluxul de lucru este setat pe Activ. Dacă fluxul de lucru nu este activ, n8n respinge cererea cu o eroare “404 / webhook not registered”, chiar dacă Your AI Connector a trimis datele corect.

Pe scurt: testează cu URL-ul de test în timp ce asculți, dar pentru ca webhook-ul să continue să funcționeze pentru contacte reale, salvează URL-ul de producție în Your AI Connector și asigură-te că fluxul de lucru este Active.

Formatul datelor webhook #

Când un webhook este declanșat, Your AI Connector trimite date structurate (JSON) către URL-ul webhook-ului dumneavoastră. Dacă utilizați o platformă de automatizare precum Zapier sau Make, aceasta analizează automat aceste date pentru dumneavoastră. Dacă construiți o integrare personalizată:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

campaign sau agent — de obicei unul, nu ambele. Dacă contul dvs. utilizează agenți, contactele sunt alocate unui agent, nu unei campanii, deci campaign apare ca null, iar agent vă indică cine a gestionat conversația. Conturile mai vechi, bazate pe campanii, văd situația invers. Citiți câmpul care este completat; nu presupuneți că campaign este întotdeauna prezent.

Blocul agent a fost introdus pe 15 august 2026. Acesta se află alături de campaign în ceea ce privește evenimentele legate de o conversație — un chat încheiat, modul „nu deranjați”, o reluare, o dezarhivare, o pauză AI, un mesaj nou, un rezumat al conversației și webhook-ul pe care îl puteți seta pe o etichetă — și conține id și name ale agentului care gestionează conversația, sau null atunci când nu este implicat niciun agent. Este pur aditiv: fiecare câmp pe care îl primiți deja rămâne neschimbat, astfel încât un receptor pe care l-ați creat înainte de acea dată va continua să funcționeze fără a fi nevoie de actualizări.

Unele evenimente adaugă propriul lor bloc suplimentar de nivel superior. De exemplu, Appointment Booked adaugă un bloc appointment (vezi Webhook-ul Appointment Booked), New Message adaugă un bloc complet message cu textul (vezi Webhook-ul New Message), iar Deliveries și Reads adaugă un bloc scurt message doar cu ID-ul și starea mesajului (vezi Webhook-ul Deliveries and Reads).

Deliveries și Reads vă spun despre ce mesaj este vorba, dar nu și ce conținea acesta. Acestea conțin un bloc message care include id și status ale mesajului — iar acel id este același messageId pe care îl returnează endpoint-ul de trimitere a mesajelor, astfel încât să puteți potrivi o confirmare de livrare sau de citire cu mesajul exact pe care l-ați trimis — dar nu conțin corpul mesajului. Replies nu conține deloc un bloc message. Dacă aveți nevoie de cuvintele trimise sau primite, abonați-vă și la New Message.

Două lucruri de știut înainte de a scrie receptorul. Nu există niciun câmp timestamp și niciun wrapper data. Fiecare bloc se află la nivelul superior al obiectului JSON, așa cum se arată mai sus.

Cele 22 de evenimente Webhook #

Cele 22 de evenimente webhook, cu eticheta de afișare pe care o bifați în aplicație și codul event trimis în payload. Codul event este un șir scurt care nu se potrivește cu eticheta de afișare, deci potriviți receptorul dvs. pe baza codului, nu a etichetei:

Încă două coduri nu apar niciodată în acea listă deoarece nu vă abonați la ele: contact_tags_updated, trimis de un URL de webhook setat pe o etichetă individuală, și summary_generated, trimis când un rezumat al chat-ului este scris pentru o etichetă din lista subscribed_to_tags a unui webhook.

Canal conectat nu este trimis încă. Apare în lista de evenimente, dar nimic nu îl emite în prezent. Nu construiți funcționalități bazate pe acesta.

Notificările bazate pe etichete și sarcini folosesc propriile forme separate. Consultați Contact Tags Updated și Task Completed.

Webhook pentru Contact Creat #

Trimis când se declanșează evenimentul Contact creat (un contact nou este adăugat manual, prin import sau prin API).

Numele evenimentului #

contactCreated

Formatul sarcinii utile (payload) #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Eșantionul de “Test” și un eveniment real arată ușor diferit. Butonul de test trimite date de substituent (John Doe, o campanie eșantion). Un eveniment real de Contact creat conține detaliile reale ale contactului, iar unele câmpuri pot fi goale în funcție de canal.

Webhook Mesaj nou #

Acest webhook se declanșează de fiecare dată când un mesaj este adăugat la o conversație, pe orice canal. Acesta acoperă ambele direcții: mesajele pe care contactul ți le trimite și mesajele pe care AI-ul, echipa ta sau o campanie le trimite acestuia. Este singurul webhook care include textul mesajului, deci acesta este cel pe care trebuie să îl folosești atunci când dorești să oglindești conversațiile într-un sistem extern.

Numele evenimentului #

new_message

Formatul sarcinii utile (payload) #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}

Încă nu există un bloc campaign în acest payload. Mesajul nou trimite contact, agent, user și message. Blocul agent a fost adăugat pe 15 august 2026 și vă indică ce agent gestionează conversația; dacă aveți nevoie și de contextul campaniei, căutați contactul prin API folosind contact.id.

Înregistrările interne ale AI-ului nu declanșează acest webhook. Pe lângă mesajele reale, platforma își păstrează propriile rânduri de evidență într-o conversație (apelurile de instrumente ale AI-ului și înregistrările interne ale turnurilor). Acelea nu sunt trimise niciodată — primești doar mesajele care au fost trimise sau primite în mod autentic.

Webhook-ul Deliveries and Reads #

Aceste două evenimente raportează ce s-a întâmplat cu un mesaj după ce a părăsit Your AI Connector: Deliveries se declanșează când un mesaj ajunge la contact (sau nu reușește), iar Reads se declanșează când contactul îl deschide, pe canalele care acceptă confirmări de citire.

Ambele conțin un bloc message cu ID-ul mesajului la care se referă evenimentul, astfel încât să puteți potrivi actualizarea cu mesajul exact pe care l-ați trimis.

Numele evenimentelor #

delivered și undelivered pentru Deliveries, read pentru Reads.

Formatul sarcinii utile (payload) #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Cum să potriviți o actualizare cu mesajul trimis. Stocați messageId pe care îl primiți când trimiteți un mesaj prin API. Când sosește o notificare Deliveries sau Reads, căutați acel ID stocat în message.id din payload — aceasta este confirmarea de livrare sau de citire pentru acel mesaj exact.

Nu există text de mesaj aici. Blocul message conține doar ID-ul și starea. Abonați-vă la New Message dacă aveți nevoie și de corpul mesajului.

Blocul message este prezent doar atunci când știm despre ce mesaj este vorba. În cazul rar al unei actualizări pe care nu o putem asocia cu un mesaj stocat, blocul este omis complet în loc să fie trimis gol — deci verificați dacă message există înainte de a citi message.id.

O notificare per schimbare de stare. Un singur mesaj trimis produce în mod normal o notificare delivered și apoi, pe canalele cu confirmări de citire, una read. O trimitere eșuată produce undelivered în schimb.

Appointment Booked Webhook #

Se declanșează atunci când un contact programează o întâlnire. Se declanșează în același mod, indiferent dacă AI-ul a programat-o în timpul unei conversații, dacă ați programat-o manual sau dacă a venit prin API.

Numele evenimentului #

booked

Formatul sarcinii utile (payload) #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id este adesea null în acest webhook, și acest lucru este normal. Evenimentul Google Calendar este creat în același moment în care este trimisă această notificare, deci ID-ul de obicei nu este încă gata. Regăsiți programarea după appointment_id puțin mai târziu dacă aveți nevoie de ea. Rămâne null permanent dacă contul nu are un Google Calendar conectat, deci nu așteptați la nesfârșit.

Butonul “Test” nu include blocul appointment. Folosiți-l pentru a confirma că punctul final răspunde, apoi faceți o programare reală pentru a vedea sarcina utilă completă.

Două cazuri în care acest webhook nu se declanșează: programările importate dintr-un calendar extern și rezervările care provin prin integrarea Formitable.

Webhook pentru actualizarea etichetelor de contact #

Se declanșează atunci când o etichetă este aplicată unui contact, iar acea etichetă are un URL de webhook configurat pentru agentul sau campania de care aparține contactul.

Numele evenimentului #

contact_tags_updated

Când se declanșează #

• O etichetă este aplicată unui contact care are un agent atribuit, o campanie atribuită sau ambele.
• Cel puțin una dintre etichetele aplicate are un URL de webhook setat în fila Etichete a acelui agent sau acelei campanii.

Dacă un contact le are pe ambele și etichetele campaniei conțin URL-uri de webhook, acelea au prioritate; în caz contrar, se folosesc cele ale agentului.

Dacă mai multe etichete cu URL-uri de webhook diferite sunt aplicate în aceeași actualizare, se trimite o cerere per URL, fiecare conținând doar etichetele care corespund acelui URL.

Eliminarea unei etichete nu trimite niciodată o cerere. Majoritatea utilizatorilor direcționează aceste URL-uri către o acțiune — colectarea unui depozit, rezervarea unui interval, alertarea unui reprezentant — astfel încât eliminarea unei etichete de pe un contact ar fi putut declanșa din nou acea acțiune. Acest lucru nu mai este posibil. O eliminare apare totuși în removed_tags atunci când are loc în aceeași actualizare cu o aplicare care merge către același URL, astfel încât o automatizare care citește ambele matrice păstrează imaginea completă; ceea ce nu va vedea niciodată este o cerere cauzată doar de o eliminare. (Modificat la 12 august 2026. Înainte de această dată, eliminările trimiteau și ele o cerere.)

Formatul sarcinii utile (payload) #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Testarea unui webhook de etichetă #

Lângă câmpul URL-ului webhook-ului din fila Etichete există un buton Test. Acesta trimite imediat un payload de probă către acel URL, astfel încât să puteți confirma că automatizarea dvs. îl primește înainte de a aștepta o conversație reală.

Testul trimite aceeași formă contact_tags_updated prezentată mai sus, folosind un contact substituent, cu eticheta pe care o testați în added_tags și un removed_tags gol. Ceea ce vede automatizarea dvs. în test este ceea ce va vedea în producție.

Două lucruri de știut:

• Salvați mai întâi eticheta. Testul caută eticheta după numele salvat, deci o etichetă nouă sau o redenumire nesalvată nu poate fi testată încă. Butonul rămâne gri până când numele de pe ecran corespunde cu cel salvat.
• Un test eșuat nu afectează webhook-ul dvs. Testele nu contribuie niciodată la oprirea automată după eșecuri repetate descrisă în Fiabilitatea Webhook-urilor.

Dacă testul eșuează, mesajul vă spune ce a răspuns endpoint-ul dvs. (de exemplu, un 404 sau 500), ceea ce este de obicei suficient pentru a identifica un URL greșit sau un flux de lucru care nu este activat.

Webhook pentru sarcină finalizată #

Doar pentru referință. Webhook-urile de sarcini (ca date) sunt documentate aici pentru dezvoltatori; evenimentele Task Created, Task Updated și Task Completed sunt selectabile în lista standard de evenimente din formularul de webhook ca oricare alt eveniment — consultați Evenimente de declanșare disponibile și Cele 22 de evenimente Webhook.

Acest payload este trimis atunci când o sarcină trece într-o etapă marcată ca etapă de finalizare. O sarcină care se mută între etape care nu sunt de finalizare trimite în schimb formatul taskUpdated.

Numele evenimentului #

taskCompleted

Când se declanșează #

• O sarcină este actualizată.
• Valoarea stage a acesteia s-a modificat față de valoarea anterioară.
• Noua etapă este configurată ca etapă de finalizare în setările etapelor de sarcini ale contului.

Formatul sarcinii utile (payload) #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Dezactivarea (sau ștergerea) unui webhook #

Fiecare webhook are un comutator pornit/oprit, chiar pe rândul său. Oprirea unuia (off) îl împiedică să primească evenimente, dar păstrează tot ce ați configurat — URL-ul, evenimentele, orice secret de semnare. Reporniți-l și va continua de unde a rămas; nimic din ce s-a întâmplat în timp ce era oprit nu va fi livrat ulterior.

Folosiți această opțiune atunci când doriți ca livrările să se oprească pentru o perioadă: punctul final este în curs de reconstrucție, depanați o integrare zgomotoasă sau întrerupeți o automatizare.

Ștergerea unui webhook (pictograma coș de gunoi de pe rândul său) îl elimină definitiv, inclusiv secretul său de semnare. Dacă doriți doar ca livrările să se oprească, opriți-l în schimb — ștergerea este pentru când ați terminat complet cu acel endpoint.

Acest lucru nu este același lucru cu dezactivarea automată a unui webhook. Dacă dezactivăm webhook-ul dumneavoastră după eșecuri repetate (consultați Fiabilitatea Webhook), comutatorul de mai sus nu îl va reactiva. Odată ce punctul final este remediat, editați webhook-ul și salvați-l cu o adresă URL modificată (orice modificare a URL-ului îl reactivează) sau apelați punctul final de reactivare prin API — sau contactați asistența și îl vom reactiva noi pentru dumneavoastră.

Payload-uri semnate (Verificarea faptului că un webhook provine într-adevăr de la noi) #

Oricine află URL-ul webhook-ului dvs. ar putea trimite o cerere falsă către acesta. Dacă acționați automat pe baza webhook-urilor — actualizarea facturării, crearea de înregistrări CRM — activarea semnării vă permite să verificați dacă fiecare cerere provine cu adevărat de la noi.

Semnarea este opțională și dezactivată implicit, și o activați pentru fiecare webhook, din vizualizarea de editare a acelui webhook (deschideți rândul unui webhook salvat).

Activarea semnării #

1. Deschideți webhook-ul (Setări → Integrări → Webhook-uri → faceți clic pe rândul webhook-ului dvs.).
2. În secțiunea Secret de semnare, faceți clic pe Generare.
3. Copiați secretul (începe cu whsec_) și stocați-l în sistemul dvs. de primire. Tratați-l ca pe o parolă.

Puteți reveni oricând pentru a dezvălui, copia, roti sau dezactiva secretul din același panou.

Ce trimitem #

Odată ce semnarea este activată, fiecare livrare pentru acel webhook conține aceste două anteturi HTTP suplimentare:

Aceste trei sunt prezente la fiecare livrare, semnată sau nu:

Cum se verifică #

Semnătura este un HMAC-SHA256 al șirului <timestamp>.<raw request body>, folosind secretul tău de semnare drept cheie.

Verificați în raport cu corpul cererii brute — octeții exacți pe care i-ați primit. Dacă framework-ul dvs. analizează JSON-ul și îl reserializează înainte de verificare, octeții se pot modifica și semnătura nu se va potrivi.

Exemplu Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Exemplu Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

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

    return hmac.compare_digest(signature, expected)

Compară semnăturile cu o funcție sigură la sincronizare (timing-safe) (timingSafeEqual / compare_digest), nu ==. Nu costă nimic și evită o clasă subtilă de atacuri.

Rotarea secretului #

Dă clic pe Rotește pentru a înlocui secretul. Comutarea este imediată: următoarea livrare este semnată doar cu noul secret. Dacă endpoint-ul tău este activ, acceptă atât secretul vechi, cât și pe cel nou timp de câteva minute, în timp ce îl implementezi pe cel nou.

Dezactivarea semnării oprește pur și simplu trimiterea antetelor de semnătură.

Reîncercarea livrărilor eșuate #

În mod implicit, o livrare care eșuează nu este reîncercată — dacă sistemul dvs. este indisponibil în acel moment, evenimentul respectiv este pierdut.

Activează Reîncearcă livrările eșuate pentru un webhook (în formularul de creare/editare) și vom continua să încercăm:

Acest interval însumează aproximativ 2 ore și 40 de minute, astfel încât un webhook poate supraviețui unei ferestre de mentenanță sau unei întreruperi scurte din partea dvs.

Ce se reîncearcă: probleme temporare — serverul dvs. returnează o eroare 5xx, un timeout sau o eroare de conexiune.

Ce nu facem: dacă endpoint-ul tău respinge cererea (orice eroare 4xx), nu reîncercăm — trimiterea aceleiași cereri din nou ar produce doar aceeași respingere.

Ce evenimente se reîncearcă: webhook-urile de etichete (contact_tags_updated), cele trei evenimente de sarcină și rezumatul zilnic. Restul sunt trimise o singură dată, deci pentru acelea comutatorul nu are nicio acțiune. Fiecare eveniment conține în continuare X-Webhook-Delivery, deci o singură regulă de eliminare a duplicatelor le acoperă pe toate.

Activează reîncercările doar dacă endpoint-ul tău este idempotent. Reîncercările înseamnă că același eveniment poate ajunge de mai multe ori. Folosește antetul X-Webhook-Delivery pentru a recunoaște o repetiție: acesta rămâne același la fiecare încercare pentru un eveniment, astfel încât poți ignora în siguranță un ID pe care l-ai procesat deja.

Reîncercările interacționează cu oprirea automată după eșecuri repetate (consultați Fiabilitatea webhook-urilor) exact așa cum v-ați dori: contorul de eșecuri numără o livrare completă, doar după ce fiecare reîncercare a fost epuizată — nu fiecare încercare individuală.

Fiabilitatea Webhook-urilor #

• Your AI Connector trimite webhook-uri printr-o conexiune securizată (HTTPS). Asigurați-vă că adresa web pe care o furnizați utilizează HTTPS.
• Dacă sistemul dumneavoastră returnează o eroare, livrarea este considerată eșuată.
• Monitorizați timpul de funcționare al sistemului de primire pentru a evita pierderea evenimentelor.
• Pentru fluxuri de lucru critice, activați Reîncercarea livrărilor eșuate și luați în considerare și un mecanism de rezervă.

Webhook-urile sunt dezactivate automat după eșecuri repetate. Dacă URL-ul webhook-ului dumneavoastră eșuează în mod repetat (aproximativ 5 erori consecutive sau 3 consecutive pentru erori de tip configurare), Your AI Connector nu mai trimite automat evenimente către acel URL. Pentru a-l reactiva odată ce punctul final este funcțional: editați webhook-ul și salvați-l cu o adresă URL modificată (orice modificare a URL-ului îl reactivează) sau utilizați punctul final de reactivare prin API — salvarea cu același URL nu este suficientă. Asistența îl poate reactiva, de asemenea, pentru dumneavoastră.

Depanare #

Pașii următori #

• Integrare GoHighLevel — utilizați webhook-uri pentru a integra Your AI Connector cu GHL.
• Acces API — combinați webhook-urile cu API-ul pentru automatizări puternice.
• Utilizarea etichetelor pentru a marca contactele — configurați etichete care declanșează webhook-urile dumneavoastră.