Riferimento API REST
L'API REST pubblica di The-Y CRM è pensata per le integrazioni server-to-server: leggere o creare contatti, conversazioni, trattative, attività e note, rispondere nelle conversazioni e ricevere eventi via webhook. Le richieste si autenticano con una chiave API. In breve: 11 ambiti di autorizzazione (scope), 11 eventi webhook firmati con HMAC-SHA256. In cloud con Free: 60 richieste al minuto e 1.000 al giorno; Cloud Pro e Paid: 300 al minuto, nessun limite giornaliero; self-hosted: nessun limite per account.
Nessun numero WhatsApp ancora collegato? API WhatsApp senza app Meta: collegare il numero, creare una chiave, aggiungere un webhook →
Autenticazione
Ogni richiesta ha bisogno della tua chiave API nell'header, come Bearer token oppure come X-API-Key:
Authorization: Bearer <YOUR_API_KEY>
# or
X-API-Key: <YOUR_API_KEY>
Crea una chiave: nell'app in Settings → Integrations (in “Advanced” → Connections) → “API keys” → nuova chiave. La chiave inizia con tyk_ e viene mostrata una sola volta: conservala al sicuro (The-Y salva solo un hash). La chiave è legata al tuo tenant.
Autorizzazioni (scope), scadenza e rinnovo: ogni chiave ha i suoi scope, che scegli quando la crei: contacts:read, contacts:write, conversations:read, conversations:write, deals:read, deals:write, tasks:write, notes:write, users:read, webhooks:manage e, dalla 1.1.67, per i negozi online, orders:write (quale route richiede quale scope lo trovi nella panoramica). Volendo le dai una data di scadenza (al massimo 5 anni). “Renew” crea una nuova chiave; quella vecchia resta valida per il tempo che scegli (scade subito, dopo 24 ore, 7 o 30 giorni). Le chiavi più vecchie senza autorizzazioni definite (prima della 1.1.60) possono ancora solo leggere e scrivere contatti: per le nuove aree imposta le autorizzazioni nelle impostazioni o crea una nuova chiave.
Panoramica: tutte le route (dalla 1.1.62)
Tutte le route si trovano sotto https://crm.the-y.at/api/ext/v1 (self-hosted: il tuo indirizzo + /api/ext/v1). Ogni route richiede uno scope della chiave.
| Opzione | Ambito | Cosa |
|---|---|---|
GET /me | – (qualsiasi chiave valida) | nome, scope e limiti della chiave stessa (ad es. per un test di connessione) |
GET /contacts, GET /contacts/{id} | contacts:read | cercare / leggere contatti |
POST /contacts, PATCH /contacts/{id} | contacts:write | creare / aggiornare un contatto |
POST /contacts/upsert | contacts:write | creare o aggiornare in base all'email (senza duplicati) |
GET /custom-fields?entity=contact|company|deal | contacts:read (trattative: deals:read) | campi personalizzati (chiave, tipo, opzioni) |
GET /conversations, GET /conversations/{id} | conversations:read | conversazioni e messaggi |
POST /conversations/{id}/messages | conversations:write | rispondere in una conversazione |
PATCH /conversations/{id} | conversations:write | stato, assegnatario |
GET /pipelines, GET /deals/{id} | deals:read | pipeline con fasi, una trattativa |
POST /deals, PATCH /deals/{id} | deals:write | creare una trattativa, cambiarne la fase |
POST /tasks | tasks:write | creare un'attività |
POST /notes | notes:write | nota su un contatto, un'azienda, una trattativa o una conversazione |
GET /users | users:read | membri attivi del team (per gli assegnatari) |
GET/POST /webhooks, GET/DELETE /webhooks/{id} | webhooks:manage | registrare e rimuovere webhook |
POST /orders | orders:write | inviare un ordine da un negozio online (dalla 1.1.67; lo fa per te il plugin “The-Y CRM for WooCommerce”: guida) |
Convenzioni
- Formato: richieste e risposte in
application/json(UTF-8). - Paginazione:
GET /contactsaccetta?limit=(1–200, default 100) e?offset=(da 0). La risposta contienelimit,offset,countehasMore.hasMoreètruenon appena la pagina è piena: la pagina successiva può quindi essere vuota. - Rate limit: 300 richieste al minuto per indirizzo IP (non per chiave), per tutte le chiamate sotto
/api/ext/v1insieme. Più chiavi usate dallo stesso server condividono un unico limite, e contano anche le richieste con una chiave sbagliata. Dalla 1.1.62 c'è anche un limite per account e piano (limiti). Se lo superi ricevi429con un headerRetry-After(in secondi; entrambi descritti nella RFC 6585): aspetta quel tempo, poi riprova. - Errori: JSON con un campo
error. Per400,401,403,404e409è una stringa (il codice), ad es.{ "error": "unauthorized" }; se alla chiave manca un'autorizzazione, questa viene indicata anche inrequired:{ "error": "insufficient_scope", "required": "contacts:write" }. Con400ricevi anche una frase leggibile inmessagee, per un campo sbagliato, il suo nome infield:{ "error": "invalid_field", "field": "first_name", "message": "…" }. La frase segueAccept-Language(inglese, tedesco o turco, altrimenti inglese): il tuo codice deve sempre controllare il codice, mai la frase. Solo429restituisce un oggetto:{ "error": { "code": "rate_limited", "message": "…" } }. La cosa più sicura è controllare prima lo stato HTTP. - Avvisi (dalla 1.1.62): se una chiamata riesce ma qualcosa non è stato ripreso, viene elencato in
warnings(solo in quel caso), ad es.{ "code": "unknown_custom_fields", "fields": ["colour"], "message": "…" }per campi personalizzati che non esistono nel CRM, ocustom_not_objectsecustomnon è un oggetto.
| Stato | Significato |
|---|---|
200 / 201 | OK / creato (eventualmente con warnings, vedi sopra) |
400 | invalid_json: il body non è un oggetto JSON valido (o è vuoto) · invalid_field: un campo ha il tipo sbagliato (vedi field; sono ammessi testo, un numero o null) · contact_empty: creazione di un contatto senza nome, cognome, email e telefono · altri codici delle nuove route: vedi codici di errore |
401 | unauthorized: chiave mancante, sconosciuta, revocata o scaduta |
403 | insufficient_scope: alla chiave manca l'autorizzazione (vedi required) · tenant_suspended: account sospeso · feature_locked: le integrazioni sono disattivate per questo account · cloud_readonly: l'account al momento è in sola lettura (ad es. dopo la fine di Cloud Pro con dati oltre i limiti di Free): creazione e aggiornamento bloccati, la lettura funziona · terms_required: nuove condizioni d'uso non ancora accettate: aggiornamento bloccato, creazione e lettura funzionano |
404 | not_found: l'elemento non esiste, è stato eliminato oppure l'ID non è un ID valido (ad es. /contacts/abc) |
409 | una risposta in una conversazione non viene inviata (ad es. window_closed, vedi conversazioni) · webhook_limit: ci sono già 100 webhook |
429 | limite superato (rate_limited oppure, sul piano Free, daily_limit_reached, con Retry-After; vedi limiti) |
500 | errore del server |
Codici di errore delle nuove route (dalla 1.1.62): 400: invalid_events, unsafe_url, invalid_status, invalid_assignee, text_required, template_not_supported, template_not_found, invalid_reference, title_required, target_required, email_required, invalid_entity (sempre con message, quasi sempre con field) · 403: limit_reached (limite mensile sul piano Free) · 409: vedi risposta, webhook_limit · 429: rate_limited, daily_limit_reached.
Limiti e piani (dalla 1.1.62)
Oltre al limite per indirizzo IP (300 richieste al minuto), ogni account ha:
| Free | Cloud Pro, Paid, Founder | self-hosted | |
|---|---|---|---|
| al minuto | 60 | 300 | nessuno (configurabile: API_LIMIT_PER_MINUTE) |
| al giorno (UTC) | 1,000 | nessuna | nessuno (configurabile: API_LIMIT_PER_DAY) |
Ogni risposta a una richiesta autenticata porta gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi Unix) per il minuto in corso; sul piano Free anche X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day e X-RateLimit-Reset-Day per il giorno (UTC). Così vedi quante richieste ti restano. In self-hosted senza un limite configurato non c'è limite e quindi nessuno di questi header. Non vengono inviati prima dell'autenticazione (chiave mancante o sbagliata).
Oltre un limite l'API risponde 429 e in più Retry-After (in secondi): { "error": { "code": "rate_limited", "message": "…", "limit": 60, "window": "minute", "retry_after": 12, "reset_at": "…" } }, oppure per il limite giornaliero { "error": { "code": "daily_limit_reached", "message": "…", "upgrade": { "href": "…" } } }. I webhook che il CRM ti invia non contano. Consiglio: con 429 aspetta i secondi indicati in Retry-After prima di riprovare.
Contatti
Gli ID dei contatti sono UUID (ad es. 3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90). In creazione e aggiornamento l'API capisce questi campi:
| Campo | Tipo | Significato |
|---|---|---|
first_name | testo | nome |
last_name | testo | cognome |
email | testo | un indirizzo email |
phone | testo | un numero di telefono |
custom | oggetto | campi personalizzati come { "key": value }. Vengono riprese solo le chiavi dei campi personalizzati che esistono per i contatti nel CRM (Settings → Custom fields, chiavi tramite GET /custom-fields). Le chiavi sconosciute non vengono salvate e sono elencate nella risposta sotto warnings |
Ogni campo accetta testo, un numero (salvato come testo, ad es. un numero di telefono da un foglio di calcolo) o null (vuoto). Un oggetto, una lista o true/false restituiscono 400 invalid_field. Gli altri campi (ad es. name, company, emails) vengono ignorati. Al momento non si può impostare un'azienda tramite l'API.
GET/contacts
Elenca i contatti, dal più recente (paginato, vedi Convenzioni). ?q= cerca in nome e cognome, email, telefono, nome dell'azienda e nome utente WhatsApp. Più parole: ciascuna deve corrispondere (ad es. nome e cognome in qualsiasi ordine). I numeri di telefono corrispondono in qualsiasi formato. Funziona anche ?search=.
# Request curl "https://crm.the-y.at/api/ext/v1/contacts?limit=20&offset=0" \ -H "Authorization: Bearer $API_KEY" # Response 200 { "data": [ { "id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90", "first_name": "Maria", "last_name": "Muster", "emails": [{ "type": "work", "value": "maria@example.com" }], "phones": [{ "type": "mobile", "value": "+4366012345678" }], "company": "ACME", "created_at": "2026-11-09T10:15:00.000Z", "wa": null } ], "limit": 20, "offset": 0, "count": 1, "hasMore": false }
company è il nome dell'azienda collegata (o null), wa l'ID WhatsApp { "bsuid", "username" } (o null). I campi personalizzati sono inclusi solo quando leggi un singolo contatto.
POST/contacts
Crea un contatto. Campi: vedi la tabella sopra.
curl -X POST "https://crm.the-y.at/api/ext/v1/contacts" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "first_name": "Maria", "last_name": "Muster", "email": "maria@example.com", "phone": "+4366012345678" }'
# Response 201 Created
{
"id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90",
"contact": {
"id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90",
"first_name": "Maria",
"last_name": "Muster",
"emails": [{ "type": "work", "value": "maria@example.com" }],
"phones": [{ "type": "mobile", "value": "+4366012345678" }],
"company": null,
…
}
}
contact ha gli stessi campi della lettura di un singolo contatto, solo senza custom. Invia insieme i campi personalizzati, ad es. "custom": { "customer_no": "K-1001" } (solo se nel CRM esiste il campo “customer_no”).
first_name, last_name, email o phone con un contenuto. Altrimenti ricevi 400 contact_empty e non viene creato nessun contatto, così come con un JSON non valido (400 invalid_json). POST /contacts non riconosce gli indirizzi email doppi: ogni chiamata crea un nuovo contatto. Per evitare duplicati usa POST /contacts/upsert.# Response 400 (empty body, or unknown fields only such as "name") { "error": "contact_empty", "message": "A contact needs at least one of these fields: first_name, last_name, email or phone." } # Response 201 with a warning (the custom field "colour" doesn't exist in the CRM – the contact is created anyway) { "id": "3f6c1e2a-…", "contact": { … }, "warnings": [ { "code": "unknown_custom_fields", "fields": ["colour"], "message": "…" } ] }
GET/contacts/{id}
Legge un singolo contatto. La risposta è il contatto stesso (senza wrapper data), con i campi personalizzati in custom.
curl "https://crm.the-y.at/api/ext/v1/contacts/3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90" \
-H "Authorization: Bearer $API_KEY"
# Response 200
{
"id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90",
"first_name": "Maria",
"last_name": "Muster",
"emails": [{ "type": "work", "value": "maria@example.com" }],
"phones": [{ "type": "mobile", "value": "+4366012345678" }],
"company_id": null,
"company": null,
"owner_user_id": null,
"owner_name": null,
"birthday": null,
"consent_state": {},
"consent_meta": {},
"created_at": "2026-11-09T10:15:00.000Z",
"wa": null,
"custom": { "customer_no": "K-1001" }
}
owner_user_id/owner_name = il responsabile, consent_state/consent_meta = consenso per canale con prova. ID sconosciuto o non valido (ad es. abc): 404 { "error": "not_found" }.
PATCH/contacts/{id}
Aggiorna in parte un contatto: cambiano solo i campi che invii, tutto il resto resta com'è:
first_name/last_name: imposta il valore;""lo cancella.email/phone: sostituisce la prima voce, gli altri indirizzi e numeri restano. Un valore vuoto non cambia nulla (rimuovere non è possibile tramite l'API).custom: imposta i campi personalizzati indicati, gli altri restano. Le chiavi sconosciute sono elencate inwarnings.- JSON non valido →
400invalid_json, tipo di campo sbagliato →400invalid_field; in questi casi non viene modificato nulla.
curl -X PATCH "https://crm.the-y.at/api/ext/v1/contacts/3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone": "+4366099999999" }'
# Response 200: { "id": "…", "contact": { … } } (same as when creating, possibly with warnings)
POST/contacts/upsert
Crea o aggiorna in base all'indirizzo email (dalla 1.1.62): { "email": "maria@example.com", "first_name": "Maria", "custom": { … } } → nuovo: 201 { "created": true, … }, esistente: 200 { "created": false, … } (cambiano solo i campi che invii). Se più contatti hanno quell'indirizzo, viene aggiornato il più vecchio e warnings contiene multiple_matches. Senza email: 400 email_required.
GET/custom-fields
GET /custom-fields?entity=contact (anche company, deal) → { "entity", "data": [{ "key", "label", "type", "options", "required" }] }. key è la chiave in custom.
Conversazioni (dalla 1.1.62)
GET /conversations?status=open&channel=whatsapp&since=2026-11-01T00:00:00Z&limit=50&offset=0: ordinate per attività più recente. Filtri facoltativi: status (open, snoozed, closed), channel (email, whatsapp, sms, webchat, messenger, instagram, call, …), since (ultimo messaggio in quel momento o dopo), contact_id. Risposta { "data": [ … ], "limit", "offset", "count", "hasMore" }.
Una conversazione: { "id", "number", "channel", "status", "priority", "subject", "contact_id", "customer": { "name", "address" }, "assignee": { "id", "name" } | null, "created_at", "last_message_at", "first_response_at", "resolved_at", "snooze_until", … }. GET /conversations/{id}?messages=200 aggiunge messages (gli ultimi, dal più vecchio): { "id", "direction": "in" | "out", "internal", "text", "author_name", "created_at", "delivery", "attachments": [{ "id", "filename", "content_type", "size" }] }. in = dal cliente, internal: true = nota interna (mai inviata al cliente).
Rispondere: POST /conversations/{id}/messages con { "text": "…" }, sullo stesso canale e account dell'inbox (email con firma, oggetto “Re:” e citazione; WhatsApp; SMS; Messenger; Instagram; web chat). Su WhatsApp, fuori dalla finestra di 24 ore, funziona solo un modello approvato: { "template": { "name": "appointment_reminder", "language": "en", "params": ["Maria"] } }. Risposta 201 { "id", "conversation_id", "delivery", "message" }; delivery come nell'inbox (sent, simulated senza un canale configurato, failed con delivery_info). Il messaggio mostra come autore “API: <key name>” e conta come una risposta dall'inbox (limite mensile sul piano Free, prima risposta). Link su WhatsApp (dalla 1.1.69.1): se il testo contiene un link (http:// o https://), il destinatario vede un'anteprima con immagine e titolo – come nell'app WhatsApp (la pagina deve avere i tag Open Graph). Con "previewUrl": false il link parte senza anteprima, ad es. { "text": "Your appointment: https://…", "previewUrl": false }. Vale solo per WhatsApp; gli altri canali ignorano il campo.
Valgono le stesse regole di una risposta dall'inbox: una risposta normale (testo o modello di servizio) viene inviata anche se il contatto si è opposto a quel canale o si è disiscritto dalle email; come nell'inbox, decidi tu (o il tuo workflow). Un modello di marketing (categoria “Marketing”) viene inviato solo con consenso esplicito. La risposta non viene inviata (409) in caso di: window_closed (finestra di 24 ore chiusa e testo libero su WhatsApp, Messenger o Instagram; su WhatsApp in quel caso funziona un modello), no_optin o consent_off (solo modello di marketing: nessun consenso esplicito o opposizione al canale), wa_thread_owned_by_other (la conversazione WhatsApp è gestita da un altro sistema di risposta), no_mailbox, recipient_suppressed, channel_not_supported. 403 limit_reached = raggiunto il limite mensile sul piano Free.
Stato / assegnatario: PATCH /conversations/{id} con { "status": "closed" }, { "status": "snoozed", "snooze_until": "…" } o { "assignee_user_id": "<ID from GET /users>" | null }. Lo storico della conversazione mostra “API (<name>) closed the conversation”.
Trattative (dalla 1.1.62)
GET /pipelines → pipeline con fasi (id, name, sort_order, probability, is_won, is_lost). GET /deals/{id} legge una trattativa. POST /deals con { "title": "Website relaunch", "value": 4800, "currency": "EUR", "stage_id": "…", "contact_id": "…", "custom": { … } } (senza fase: prima fase della pipeline predefinita). PATCH /deals/{id} con { "stage_id": "…" }: la pipeline segue la fase, vinta / persa dipendono dalla fase. ID di un altro account → 400 invalid_reference con field.
Attività, note, team (dalla 1.1.62)
POST /taskscon{ "title", "description", "due_at", "priority": "low|normal|high|urgent", "kind": "todo|callback|call|email|follow_up", "assignee_user_id", "contact_id" | "company_id" | "deal_id" | "conversation_id" }(al massimo un elemento collegato). Chi ha creato la chiave risulta come autore dell'attività.POST /notescon{ "text", "contact_id" | "company_id" | "deal_id" | "conversation_id" }(esattamente un elemento collegato): su una conversazione è una nota interna.GET /users→{ "data": [{ "id", "name", "email", "roles" }] }(solo membri attivi del team).GET /me→ nome, scope e limiti della chiave stessa: comodo come test di connessione.
Webhook in uscita (eventi)
Invece di interrogare di continuo l'API (polling), fatti inviare gli eventi al tuo URL. In Settings → Integrations → “Send data (webhook)” imposti un URL di destinazione e gli eventi. Il CRM crea il secret per la firma.
Registrare tramite l'API (dalla 1.1.62): POST /webhooks con { "url": "https://…", "events": ["message.received", "deal.won"], "name": "My system" }; "events": ["*"] = tutti. Risposta 201 { "id", "secret": "whsec_…", "webhook" }. Il secret compare solo in questa risposta, mai più (né l'elenco né la lettura singola lo mostrano). DELETE /webhooks/{id} rimuove il webhook. Al massimo 100 webhook per account.
| Evento | Quando | data |
|---|---|---|
contact.created | contatto creato: a mano, tramite l'API, da WhatsApp, email, SMS, chiamate, web chat, prenotazioni, appuntamenti; le importazioni CSV solo con la casella “Run automations, … campaigns and webhooks …” spuntata | contatto + source (whatsapp, email, import, api, …) |
contact.updated | modificato nel modulo, nell'inbox o tramite l'API | contatto + changed |
message.received | un cliente scrive | messaggio: text, conversation_id, channel, contact_id, from { name, address }, first |
conversation.created | un cliente o il team avvia una conversazione | conversazione + started_by (customer / team) |
conversation.closed / conversation.assigned | chiusa / nuovo assegnatario | conversazione (+ previous_status / previous_assignee_id) |
deal.created, deal.stage_changed, deal.won, deal.lost | trattative | trattativa (+ from_stage, to_stage ai cambi di fase) |
task.created | attività creata | attività |
- Body: The-Y invia una richiesta
POSTcon JSON al tuo URL, ad es.{ "id": "evt_4b0c…", "event": "contact.created", "tenant": "<account ID>", "at": "2026-11-08T12:00:00.000Z", "data": { … } }.idè l'ID dell'evento (dalla 1.1.62), lo stesso dell'headerX-TheY-Event-Id. I contatti hanno indatagli stessi campi che tramite l'API (id,name,first_name,last_name,emailephone= la prima voce,emails,phones,company, …).data.origindice chi l'ha causato (customer,user,system,automation,api): così un workflow può saltare gli eventi che ha causato lui stesso tramite l'API. - Cosa non arriva (ancora): le conversazioni che il CRM avvia da solo con un messaggio (centralino, flusso) non inviano
conversation.created. - Destinazione: solo indirizzi
http(s)pubblici. Il CRM rifiuta le destinazioni interne (rete di casa o aziendale,localhost, servizi Docker, metadati cloud) già al salvataggio e non le chiama mai durante l'invio, nemmeno dopo un redirect (in self-hosted,WEBHOOK_PRIVATE_TARGETS=onpermette destinazioni nella tua rete). Al massimo 4 consegne contemporanee per webhook, le altre seguono in ordine. - Nuovi tentativi: con
429,5xx, un errore di rete o se il tuo endpoint non risponde entro 8 secondi: fino a 3 tentativi in rapida successione, con lo stesso ID evento (X-TheY-Event-Ideidnel body), lo stesso IDX-TheY-Delivery, lo stesso timestamp e la stessa firma. Se il tuo endpoint risponde troppo lentamente, la stessa consegna arriva più di una volta: tieni traccia degli ID degli eventi delle ultime ore ed elabora ognuno una sola volta. La cosa migliore: rispondi subito2xxed elabora dopo. - In pausa dopo i fallimenti: se la consegna fallisce 50 volte di fila (per evento, dopo tutti i tentativi), il webhook va in pausa: il CRM smette di inviare lì e mostra in Settings → Integrations “Paused after 50 failures in a row” con l'ultimo errore. Tutti quelli che possono gestire i webhook ricevono una notifica (nell'app, e via email se le notifiche email sono attive). Riparte con “Send again” (azzera il contatore e invia subito una consegna di prova), modificando o riattivando il webhook, oppure con “Renew secret”. Inoltre il CRM invia da solo una consegna di prova ogni 6 ore: se arriva, il webhook ricomincia a inviare. Gli eventi del periodo di pausa non vengono consegnati in seguito.
- Consegna di prova: evento
webhook.pingcon{ "webhook_id": "…" }indata, firmato come ogni evento. Agli eventi che non conosci rispondi semplicemente con2xx.
message.received, conversation.* e contact.*, testi dei messaggi, nomi, numeri di telefono e indirizzi email dei tuoi clienti vanno all'indirizzo che inserisci (ad esempio il tuo strumento di automazione). Il CRM invia solo ciò a cui ti iscrivi, e solo a destinazioni inserite da un admin. Verifica che il sistema di destinazione possa trattare questi dati (accordo sul trattamento dei dati, sede dei server) e iscriviti solo agli eventi che ti servono. Lo stesso vale per le chiavi API con conversations:read e users:read (indirizzi email del tuo team). Invia i webhook solo tramite https://.Verificare la firma del webhook (dalla 1.1.60)
Ogni consegna è firmata, così il tuo sistema può verificare che i dati arrivino davvero da The-Y CRM e non siano stati modificati lungo il percorso.
Secret: viene mostrato una volta quando crei il webhook (whsec_…). Poi viene salvato solo cifrato e non è più visibile da nessuna parte. L'hai perso? “Renew secret”: quello vecchio smette subito di funzionare.
| Header | Contenuto |
|---|---|
X-TheY-Timestamp | ora della consegna in secondi dal 1970 (Unix time) |
X-TheY-Signature | v1=<hex> – HMAC-SHA256 (metodo HMAC) con il secret su <X-TheY-Timestamp>.<body> (timestamp, un punto, il body invariato) |
X-TheY-Event | e.g. contact.created |
X-TheY-Event-Id | ID dell'evento (evt_…, dalla 1.1.62). È lo stesso a ogni nuovo tentativo e per tutti i webhook dello stesso evento; si trova anche nel body firmato come id. Usalo per riconoscere le consegne doppie |
X-TheY-Delivery | ID di questa consegna a questo webhook (resta lo stesso nei nuovi tentativi) |
X-KSCRM-Signature, X-KSCRM-Event | vecchio: HMAC-SHA256 solo sul body, senza timestamp. Viene ancora inviato perché i ricevitori esistenti non smettano di funzionare |
X-KSCRM-Signature verrà rimosso con la versione 1.2.0. Fino ad allora verifica X-TheY-Signature come mostrato qui sotto.Come verificare: calcola tu la firma e confrontala in tempo costante, e rifiuta le consegne il cui timestamp si discosta di più di 5 minuti dal tuo orologio (protegge dal riutilizzo di consegne intercettate). Importante: firma il body grezzo, così come lo ricevi, senza prima interpretarlo come JSON e serializzarlo di nuovo.
# Node.js (Express)
import crypto from "node:crypto";
import express from "express";
const SECRET = process.env.THEY_WEBHOOK_SECRET; // whsec_…
const app = express();
const alreadyProcessed = new Set(); // in real life rather a table/Redis entry that expires after e.g. 24 h
app.post("/the-y/webhook", express.raw({ type: "application/json" }), (req, res) => {
const ts = Number(req.get("X-TheY-Timestamp"));
const sig = (req.get("X-TheY-Signature") || "").split(",").map((s) => s.trim()).find((s) => s.startsWith("v1="))?.slice(3) || "";
if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return res.status(400).send("too old");
const want = crypto.createHmac("sha256", SECRET).update(`${ts}.${req.body.toString("utf8")}`).digest("hex");
const a = Buffer.from(sig, "utf8"), b = Buffer.from(want, "utf8");
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).send("bad signature");
const event = JSON.parse(req.body.toString("utf8"));
if (alreadyProcessed.has(event.id)) return res.sendStatus(204); // retry – process only once
alreadyProcessed.add(event.id);
// … process event.event, event.data
res.sendStatus(204);
});
# PHP
<?php
$secret = getenv('THEY_WEBHOOK_SECRET'); // whsec_…
$body = file_get_contents('php://input');
$ts = (int)($_SERVER['HTTP_X_THEY_TIMESTAMP'] ?? 0);
$sigHdr = $_SERVER['HTTP_X_THEY_SIGNATURE'] ?? '';
$sig = '';
foreach (explode(',', $sigHdr) as $part) { $part = trim($part); if (str_starts_with($part, 'v1=')) $sig = substr($part, 3); }
if (abs(time() - $ts) > 300) { http_response_code(400); exit('too old'); }
$want = hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($want, $sig)) { http_response_code(401); exit('bad signature'); }
$event = json_decode($body, true);
// … process $event['event'], $event['data']
http_response_code(204);
Webhook in entrata
I sistemi esterni possono creare/aggiornare dati in The-Y tramite un URL con token: POST /api/hooks/<token> (token creato in Integrations). Per ogni webhook scegli il livello di accesso: upsert (solo creare/aggiornare, le eliminazioni vengono ignorate: contro il lock-in) o full (eliminazione compresa).
