Ausgehende Postbacks

Postbacks senden neue AdTarget-Conversion-Ereignisse an Ihren Server. Sie sind von der eingehenden REST-API getrennt: Bestehende API-Schlüssel, Anfragen, Attribution und die Übermittlung an Werbeplattformen funktionieren weiterhin.

Telegram-Ereignisse

Der erste Bereich leitet unverarbeitete Telegram-Updates weiter, keine Werbe-Conversions. Wählen Sie ein Ziel und aktivieren Sie business_message (Business-Direktnachrichten), business_connection, chat_join_request und/oder chat_member (Beitritte, Austritte und Statusänderungen).

Die Konfiguration gilt für einen Bot im gesamten Konto, nicht nur für eine Website. Das Ziel erhält Nachrichteninhalte und Telegram-Identitäten aus den ausgewählten Updates. Konfigurieren Sie nur ein Backend, das Sie selbst kontrollieren. Der Zustellungsverlauf gehört zu der Website, auf der das Ziel ursprünglich konfiguriert wurde.

Neue allgemeine Weiterleitungen senden einen JSON-Body mit update_id und dem ausgewählten Telegram-Update-Objekt in unveränderter Form. Sie verwenden die unten beschriebenen Signatur- und Zustellungsheader X-AdTarget-*, eine dauerhafte Warteschlange und bis zu sechs Versuche. Wiederholte Telegram-Update-IDs werden innerhalb des aufbewahrten Zustellungsverlaufs dedupliziert. Dabei werden keine Lead-, Purchase- oder anderen Werbeereignisse erstellt.

Bestehende TSA-/Ross-Integration

Die bestehende TSA-Weiterleitung wird mit ihrer aktuellen URL und den aktivierten Telegram-Typen angezeigt. Sie behält das bisherige Ziel /telegram/proxy, die Authentifizierung über X-Forward-Secret / X-Forward-Timestamp, die unverarbeiteten Telegram-Nutzdaten mit ergänzten Herkunftsinformationen und ihre bisherige Wiederholungsstrategie bei. Sie verwendet weder das allgemeine HMAC-Protokoll noch die neuen Conversion-Schalter. Sie bleibt der einzige Sender für TSAWelcomeBot; es erfolgen weder die automatische Einrichtung eines zweiten Senders noch eine Rotation des Geheimnisses, eine erneute Zustellung früherer Ereignisse oder eine Migration des Empfängers. Frühere Zustellungen werden nicht nachträglich zum allgemeinen Zustellungsverlauf hinzugefügt.

Diese geschützte bestehende Integration kann in diesem Editor nur eingesehen werden. Sie wird beim Aktivieren neuer Weiterleitungen für andere Bots bewusst nicht ersetzt.

Conversion-Ereignisse (optional)

Klappen Sie Conversion-Ereignisse — optional auf, um neue AdTarget-Conversion-Datensätze weiterzuleiten, einschließlich Conversions, die über die eingehende REST-API empfangen werden. Diese Schalter steuern nicht die oben beschriebene Telegram-Weiterleitung.

Conversion-Zustellung konfigurieren

Öffnen Sie Website → Einstellungen → Postbacks, geben Sie eine öffentliche HTTPS-URL ein, wählen Sie die Ereignistypen und aktivieren Sie die Zustellung. Speichern Sie, kopieren Sie das nur einmal angezeigte Signaturgeheimnis und wählen Sie anschließend Test senden. Die Warteschlange beginnt normalerweise innerhalb einer Minute mit der Zustellung. Nur der Website-Inhaber kann die Konfiguration ändern; die Administratorvorschau ist schreibgeschützt.

Unterstützte Typen: Lead, Purchase, CompleteRegistration, Subscribe, Contact und Custom. Die Auswahl von Custom umfasst alle benutzerdefinierten Namen; unterscheiden Sie diese anhand von data.customEventName. Dies sind Conversion-Typen, keine Seitenaufrufe, unverarbeiteten Telegram-Beitritte oder -Austritte oder abgeleiteten Geschäftsphasen wie QFTD. Ein Beitritt verwendet das für diesen Kanal konfigurierte Conversion-Ereignis.

Es werden nur neue Conversions gesendet, die nach der Aktivierung erstellt werden. Bestehende Verlaufsdaten, spätere Wertänderungen und bereits vorhandene Conversions, die von der eingehenden API wiederverwendet werden, werden nicht erneut zugestellt. Eine Migration historischer Daten ist nicht erforderlich. Ereignisse ohne zugeordnete Website können nicht an den Endpunkt einer Website zugestellt werden.

Das Speichern der Einstellungen storniert ausstehende Zustellungen der vorherigen Konfiguration. Das Deaktivieren stoppt Zustellungen in der Warteschlange; eine bereits laufende Anfrage kann noch abgeschlossen werden. Verwenden Sie einen öffentlichen Hostnamen, der über IPv4 erreichbar ist, mit HTTPS auf Port 443. Private Adressen und Weiterleitungen werden blockiert.

Anfrage

AdTarget sendet eine POST-Anfrage mit 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 ist die Unix-Zeit in Millisekunden. Optionale Felder werden weggelassen, wenn sie nicht vorhanden sind. Namen, E-Mail-Adressen, Telefonnummern, IP-Adressen, API-Schlüssel und Zugangsdaten für Werbeplattformen sind nicht enthalten. Ein Test verwendet event: "test" und eine Beispielnachricht; er erstellt keine Conversion und sendet nichts an Ihre Werbepixel.

Authentizität prüfen

Speichern Sie das Geheimnis auf Ihrem Server. Prüfen Sie diese Header:

• X-AdTarget-Delivery-Id: bleibt bei erneuten Versuchen gleich; verwenden Sie ihn, um eine mehrfache Verarbeitung zu verhindern.
• X-AdTarget-Timestamp: Unix-Zeit in Sekunden, bei jedem Versuch aktualisiert.
• X-AdTarget-Signature: sha256=, gefolgt vom hexadezimalen HMAC-SHA256 von timestamp + "." + rawRequestBody, signiert mit Ihrem Geheimnis.

Prüfen Sie die Signatur anhand der ursprünglichen Body-Bytes vor dem Parsen von JSON, lehnen Sie Zeitstempel außerhalb eines Zeitfensters von fünf Minuten ab und vergleichen Sie Signaturen in konstanter Zeit. Speichern Sie die Zustellungs-ID atomar zusammen mit Ihrem Geschäftsvorgang, damit ein erneuter Versuch diesen nicht wiederholt. Antworten Sie mit einem 2xx-Status, nachdem Sie die Anfrage dauerhaft angenommen haben.

Zuverlässigkeit

Die Zustellung erfolgt mindestens einmal, nicht genau einmal. Ein Timeout, nachdem Ihr Server ein Ereignis bereits angenommen hat, kann ein Duplikat verursachen. Es gibt insgesamt bis zu sechs Versuche mit zunehmenden Wartezeiten. HTTP-Weiterleitungen und andere Antworten außerhalb von 2xx gelten als Fehler. Die DNS-Auflösung ist auf fünf Sekunden und die HTTP-Anfrage auf zehn Sekunden begrenzt.

Der Zustellungsverlauf zeigt die letzten 50 Anfragen, Versuche, den Status und den HTTP-Code. Abgeschlossene Einträge werden 30 Tage lang aufbewahrt. Ein fehlgeschlagener Postback ändert weder die Antwort der eingehenden API noch den Status der Conversion-Übermittlung an Meta/TikTok/Snapchat. Vermeiden Sie Schleifen: Senden Sie nicht jeden ausgehenden Postback als neues eingehendes Ereignis an AdTarget zurück.