Postback in uscita
I postback inviano nuovi eventi di conversione AdTarget al tuo server. Sono separati dall’API REST in ingresso: le chiavi API esistenti, le richieste, l’attribuzione e l’invio alle piattaforme pubblicitarie continuano a funzionare.
Eventi Telegram
La prima sezione inoltra aggiornamenti Telegram originali, non conversioni pubblicitarie. Scegli una destinazione e seleziona business_message (messaggi diretti Business), business_connection, chat_join_request e/o chat_member (ingressi, uscite e cambiamenti di stato).
La configurazione appartiene a un bot a livello di account, non a un solo sito. La destinazione riceve il contenuto dei messaggi e le identità Telegram presenti negli aggiornamenti selezionati. Configura solo un backend che controlli. La cronologia degli invii appartiene al sito in cui è stata configurata inizialmente la destinazione.
I nuovi inoltri generici inviano un corpo JSON contenente update_id e l’oggetto dell’aggiornamento Telegram selezionato, senza modificarlo. Usano le intestazioni di firma e consegna X-AdTarget-* descritte di seguito, una coda persistente e fino a sei tentativi. Gli ID degli aggiornamenti Telegram ripetuti vengono deduplicati all’interno della cronologia degli invii conservata. Questi inoltri non creano eventi Lead, Purchase o altri eventi pubblicitari.
Integrazione TSA / Ross esistente
L’inoltro TSA esistente viene mostrato con il suo URL attuale e i tipi Telegram abilitati. Mantiene la destinazione /telegram/proxy, l’autenticazione X-Forward-Secret / X-Forward-Timestamp, il payload Telegram originale arricchito con informazioni sulla provenienza e la politica di tentativi già in uso. Non utilizza il protocollo HMAC generico né i nuovi interruttori delle conversioni. Rimane l’unico mittente per TSAWelcomeBot; non vengono introdotti automaticamente un secondo mittente, una rotazione del segreto, un reinvio dello storico o una migrazione del destinatario. Gli invii precedenti non vengono aggiunti retroattivamente alla cronologia degli invii generici.
Questa integrazione esistente protetta è in sola lettura in questo editor. Non viene sostituita quando si attivano nuovi inoltri per altri bot.
Eventi di conversione (facoltativi)
Espandi Eventi di conversione — facoltativi per inoltrare i nuovi record di conversione AdTarget, comprese le conversioni ricevute tramite l’API REST in ingresso. Questi interruttori non controllano l’inoltro Telegram descritto sopra.
Configurare l’invio delle conversioni
Apri Sito → Impostazioni → Postback, inserisci un URL HTTPS pubblico, seleziona i tipi di evento e abilita l’invio. Salva, copia il segreto di firma mostrato una sola volta, quindi scegli Invia test. La coda avvia normalmente gli invii entro un minuto. Solo il proprietario del sito può modificare la configurazione; l’anteprima amministratore è in sola lettura.
Tipi supportati: Lead, Purchase, CompleteRegistration, Subscribe, Contact e Custom. Selezionando Custom vengono inclusi tutti i nomi personalizzati; usa data.customEventName per distinguerli. Si tratta di tipi di conversione, non di visualizzazioni di pagina, ingressi/uscite Telegram originali o fasi commerciali derivate come QFTD. Un ingresso utilizza l’evento di conversione configurato per quel canale.
Vengono inviate solo le nuove conversioni create dopo l’attivazione. Lo storico esistente, le successive modifiche al valore e le conversioni già esistenti riutilizzate dall’API in ingresso non vengono reinviati. Non è necessaria una migrazione dello storico. Gli eventi senza un sito identificato non possono essere inviati all’endpoint di un sito.
Salvare le impostazioni annulla gli invii in sospeso della configurazione precedente. Disabilitare l’invio arresta le consegne in coda; una richiesta già in corso può completarsi. Usa un nome host pubblico che risolva a un indirizzo IPv4, con HTTPS sulla porta 443. Gli indirizzi privati e i reindirizzamenti sono bloccati.
Richiesta
AdTarget invia una richiesta POST con Content-Type: application/json:
{
"version": 1,
"event": "Purchase",
"occurredAt": 1789300000000,
"data": {
"conversionId": "conversion-id",
"websiteId": "atid_example",
"telegramUserId": 123456789,
"value": 97,
"currency": "EUR",
"contentName": "VIP"
}
}occurredAt è il tempo Unix in millisecondi. I campi facoltativi vengono omessi quando assenti. Nomi, indirizzi email, numeri di telefono, indirizzi IP, chiavi API e credenziali pubblicitarie non sono inclusi. Un test usa event: "test" e un messaggio di esempio; non crea una conversione e non invia nulla ai tuoi pixel pubblicitari.
Verificare l’autenticità
Conserva il segreto sul tuo server. Controlla queste intestazioni:
X-AdTarget-Delivery-Id: rimane invariato tra i tentativi; usalo per evitare elaborazioni duplicate.X-AdTarget-Timestamp: tempo Unix in secondi, aggiornato a ogni tentativo.X-AdTarget-Signature:sha256=seguito dall’HMAC-SHA256 esadecimale ditimestamp + "." + rawRequestBody, firmato con il tuo segreto.
Verifica la firma sui byte originali del corpo prima del parsing JSON, rifiuta i timestamp al di fuori di una finestra di cinque minuti e confronta le firme in tempo costante. Memorizza l’ID di consegna in modo atomico insieme all’operazione applicativa, così un nuovo tentativo non può ripeterla. Restituisci uno stato 2xx dopo aver accettato la richiesta in modo persistente.
Affidabilità
La consegna avviene almeno una volta, non esattamente una volta. Un timeout dopo che il server ha accettato un evento può causare un duplicato. Sono previsti fino a sei tentativi complessivi, con intervalli crescenti. I reindirizzamenti HTTP e le altre risposte diverse da 2xx sono considerati errori. La risoluzione DNS è limitata a cinque secondi e la richiesta HTTP a dieci secondi.
La cronologia mostra le ultime 50 richieste, i tentativi, lo stato e il codice HTTP. Le voci completate vengono conservate per 30 giorni. Un postback non riuscito non modifica la risposta dell’API in ingresso né lo stato dell’invio delle conversioni a Meta/TikTok/Snapchat. Evita i cicli: non reinviare ogni postback in uscita ad AdTarget come nuovo evento in ingresso.