Salt la conținutul principal
Webhook-urile permit AgencyHandy să trimită date către sistemele dvs. externe în momentul în care ceva se schimbă — fără polling. Când un eveniment configurat se declanșează (de exemplu, o comandă este actualizată sau un tichet este creat), AgencyHandy trimite o solicitare HTTP POST cu un payload JSON la URL-ul endpoint-ului pe care îl specificați. Acest lucru facilitează sincronizarea instrumentelor externe precum CRM-uri, sisteme de facturare sau tablouri de bord personalizate cu spațiul dvs. de lucru AgencyHandy în timp real.
Spațiile de lucru cu planul Business Pro acceptă până la 30.000 de evenimente webhook per perioadă de facturare. Verificați limitele planului dvs. înainte de a configura automatizări cu volum mare.

​
Evenimente acceptate

Puteți abona un webhook la orice combinație de evenimente de mai jos:
CategorieEvenimente
ServiciuCreat, Actualizat, Șters
ComandăCreată, Actualizată, Ștearsă
SarcinăCreată, Atribuită, Finalizată, Actualizată
FacturăStatus modificat
Client / UtilizatorClient nou adăugat, Client/utilizator șters
PropunereTrimisă, Primită, Acceptată, Respinsă
TichetCreat, Atribuit, Status modificat
PlatăPrimită, Eșuată
Pachet de serviciiCreat, Actualizat, Șters

​
Creați un webhook

1

Navigați la Gestionarea webhook-urilor

În bara laterală din stânga, accesați Integrări → Gestionare Webhooks.
2

Autentificați token-ul dvs.

Faceți clic pe butonul Management pentru a vă autentifica token-ul webhook. Acest token este folosit pentru a semna payload-urile trimise, astfel încât să puteți verifica că provin din AgencyHandy.
3

Creați un webhook nou

Faceți clic pe Creați Webhook Nou pentru a deschide formularul de configurare a webhook-ului.
4

Introduceți URL-ul endpoint-ului

În câmpul URL Endpoint, introduceți URL-ul sistemului extern care ar trebui să primească datele webhook. Acesta trebuie să fie un endpoint POST accesibil public.
5

Selectați tipul de conținut

Alegeți JSON ca tip de conținut. AgencyHandy trimite toate payload-urile webhook ca application/json.
6

Selectați evenimentele webhook

Alegeți fiecare eveniment care ar trebui să declanșeze acest webhook. Puteți selecta evenimente din mai multe categorii — de exemplu, Comandă: Creată și Factură: Status modificat pot indica ambele același endpoint.
7

Activați webhook-ul

Comutați butonul radio Activ. Când este activ, AgencyHandy livrează payload-uri pentru toate evenimentele selectate la endpoint-ul dvs. în timp real.
8

Salvați configurarea

Examinați setările, apoi faceți clic pe Salvare. Webhook-ul apare în listă și începe să livreze evenimente imediat.

​
Testați un webhook

După crearea unui webhook, trimiteți un payload de test pentru a confirma că endpoint-ul dvs. este accesibil și procesează datele corect.
1

Deschideți webhook-ul

Din lista de Gestionare Webhooks, faceți clic pe webhook-ul pe care doriți să îl testați.
2

Faceți clic pe Eveniment de test

Faceți clic pe butonul Test Event de pe pagina de detalii a webhook-ului.
3

Selectați un eveniment de test

Alegeți un eveniment de exemplu din lista de evenimente configurate pe acest webhook (ex.: Comandă: Creată).
4

Trimiteți payload-ul de test

Faceți clic pe Trimite. AgencyHandy postează un payload de exemplu la URL-ul endpoint-ului dvs.
5

Verificați rezultatul

Verificați sistemul dvs. extern pentru a confirma că payload-ul de test a ajuns și a fost procesat conform așteptărilor. Înapoi în AgencyHandy, faceți clic pe webhook pentru a-i examina istoricul — puteți vedea solicitarea completă, răspunsul returnat de endpoint-ul dvs. și puteți re-livra orice eveniment trecut dacă este necesar.
Utilizați un instrument precum Webhook.site sau RequestBin ca endpoint temporar în timpul configurării pentru a inspecta forma exactă a payload-ului înainte de a conecta sistemul real.

​
Autentificați payload-urile webhook

Fiecare solicitare webhook trimisă de AgencyHandy include un header de semnătură pe care endpoint-ul dvs. îl poate utiliza pentru a verifica că payload-ul este autentic și nu a fost modificat.

​
Header-ul de semnătură

x-ah-sig: <signature>
AgencyHandy adaugă acest header la fiecare solicitare webhook. Extrageți valoarea din solicitările primite și transmiteți-o la endpoint-ul de verificare.

​
Verificați o semnătură webhook

Trimiteți următoarea solicitare pentru a confirma că un payload este autentic: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
obligatoriu
ID-ul webhook-ului care a primit evenimentul. Găsiți-l pe pagina de detalii a webhook-ului din AgencyHandy.
​
signature
string
obligatoriu
Valoarea header-ului x-ah-sig din solicitarea webhook primită.
​
secret
string
obligatoriu
Secretul webhook afișat pe pagina de detalii a webhook-ului din AgencyHandy.
​
payload
object
obligatoriu
Corpul JSON brut primit din solicitarea webhook a AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Răspunsuri
​
verification_status
string
SUCCESS când semnătura este validă. FAILED când verificarea eșuează (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Păstrați secretul webhook-ului confidențial. Rotiți-l periodic și actualizați logica de verificare imediat după rotire. Nu îl expuneți niciodată în codul din partea clientului sau în depozitele publice.

​
Note importante

  • URL-ul endpoint-ului dvs. trebuie să fie un URL HTTPS POST accesibil public.
  • Dacă endpoint-ul dvs. este temporar indisponibil, verificați panoul de istorici al webhook-ului din AgencyHandy — puteți re-livra orice eveniment trecut direct de acolo.
  • Monitorizați regulat activitatea webhook-urilor pentru a detecta livrările eșuate sau tentativele de acces neautorizat.
  • Webhook-urile care eșuează în mod repetat pot fi suspendate de AgencyHandy — examinați jurnalele de livrare pentru a depista problemele din timp.