Webhooks
Richten Sie einen Webhook ein, damit Webmetic neue Besuche von Unternehmen an Ihr System sendet.
Zum Beispiel liest ein Maschinenbauer zum ersten Mal Ihre Preisseite. Wenige Minuten, nachdem der Besuch im Dashboard erscheint, steht das Unternehmen als neuer Lead in Ihrem CRM.
Ein Webhook meldet Unternehmen, keine Personen, und Sie müssen dafür nicht die API abfragen.
- 1BesuchWebmetic ordnet einen Besuch auf Ihrer Website einem Unternehmen zu.
- 2EreignisWenn der Besuch zu Ihrem Webhook passt, legt Webmetic ein Ereignis an.
- 3ZustellungWebmetic sendet das Ereignis als signierte POST-Anfrage an Ihre URL.
- 4AntwortWenn Ihr System nicht mit 2xx antwortet, versucht Webmetic es später noch einmal.
Bevor Sie beginnen
- Dauer: Die Einrichtung im Dashboard dauert wenige Minuten, und dazu kommt die Zeit für den Empfänger in Ihrem System.
- Konto: Sie brauchen ein Webmetic-Konto mit mindestens einer Website.
- Zugang: Sie brauchen eine öffentliche HTTPS-Adresse, die POST-Anfragen annimmt.
- Rechte: Im Dashboard richten nur Admins Webhooks ein. Über die API brauchen Sie den Visitor-Intelligence-Schlüssel, den nur Admins unter Menü > Integrationen > API sehen.
- Plan: Webhooks sind in jedem Plan verfügbar, aber im Free-Plan meldet Webmetic nur die Unternehmen, die Sie in diesem Plan sehen. Mehr dazu unter Pläne.
- Kosten: Webhooks kosten keine Credits.
Ereignisse
Jeder Webhook wartet auf bestimmte Ereignisse, die im Dashboard deutsche Namen tragen und in der API nach ihrem Typ heißen:
| Typ | Im Dashboard | Wann Webmetic es sendet |
|---|---|---|
company.identified | Neues Unternehmen | Ein Unternehmen ist zum ersten Mal auf Ihrer Website. Einmal pro Unternehmen und Website. |
company.returned | Wiederkehrendes Unternehmen | Ein bekanntes Unternehmen ist wieder da. Einmal pro Besuch. |
company.intensive_visit | Interessiertes Unternehmen | Ein Besuch dauert insgesamt mindestens 30 Sekunden. Einmal pro Besuch. |
segment.entered | Neu im Segment | Ein Unternehmen mit neuem Besuch passt ab jetzt in ein Segment. Einmal pro Unternehmen und Segment. |
Webmetic sendet ein Ereignis wenige Minuten, nachdem der Besuch im Dashboard erscheint. Ein Besuch kann zwei Ereignisse auslösen, zum Beispiel Neues Unternehmen und Interessiertes Unternehmen.
Ein neuer Webhook meldet Besuche ab seiner Einrichtung, und er meldet Unternehmen, die Ihre Website schon vorher besucht haben, als wiederkehrend. Wenn Ihre Website schon einen Webhook hat oder hatte, kann ein neuer Webhook auch Besuche aus den 48 Stunden vor seiner Einrichtung melden, die Webmetic erst danach fertig verarbeitet hat. Besuche, die Webmetic keinem Unternehmen zuordnet, lösen kein Ereignis aus.
Webhook anlegen
- Öffnen Sie Menü > Integrationen > Webhooks.
- Klicken Sie auf Neuer Webhook. Das Fenster Neuer Webhook öffnet sich.
- Geben Sie unter URL die Adresse Ihres Empfängers ein, beginnend mit
https://. - Optional: Geben Sie eine Bezeichnung ein, die als Name in der Liste erscheint.
- Wählen Sie ein Ereignis, denn im Dashboard hat jeder Webhook genau eines.
- Wählen Sie die Websites. Zu Beginn sind alle Websites Ihres Kontos ausgewählt.
- Wenn Sie Neu im Segment gewählt haben, wählen Sie unter Segment ein Segment dieser Websites.
- Optional: Öffnen Sie Erweitert.
- Klicken Sie auf Header hinzufügen und tragen Sie bis zu drei eigene Header ein, zum Beispiel einen Schlüssel für Ihr System.


- Klicken Sie auf Webhook anlegen. Webmetic legt den Webhook an und zeigt sein Secret.
- Wenn Ihr System die Signatur prüft, kopieren Sie das Secret, denn Webmetic zeigt es nur dieses eine Mal.
- Klicken Sie auf Verstanden.


Webhooks aus der API stehen auch in der Liste im Dashboard. Über die API können Sie Webhooks auflisten und löschen.
Datenformat
Jede Zustellung ist eine POST-Anfrage mit JSON in UTF-8. Der Body hat immer diese Felder:
id: die Kennung des Ereignisses ausevt_und 16 Zeichen, die auch bei Wiederholungen gleich bleibt.type: der Typ des Ereignisses, zum Beispielcompany.returned.created_at: wann Webmetic das Ereignis angelegt hat.test:truebei Test-Ereignissen.website: die Website, auf der der Besuch war.data.company: das Unternehmen mit den Feldern vonGET /company, ohne die Felder, die Webmetic nicht kennt.data.visit: der Besuch mit seinen Seitenaufrufen inuser_data, unbekannte Werte alsnull.data.segment:idundlabeldes Segments beisegment.entered, sonstnull.data.truncated:true, wenn Webmetic den Body gekürzt hat.
Zeitangaben stehen in UTC mit Z. Mehr dazu unter Zeiträume und Zeitzonen.
Der Body hat höchstens 50.000 Bytes. Wenn er größer wird, lässt Webmetic zuerst die ältesten Seitenaufrufe weg. Wenn das nicht reicht, setzt Webmetic lange Beschreibungen und danach die größten Unternehmensfelder auf null. In beiden Fällen ist data.truncated dann true.
Dazu kommen die Header Webmetic-Event mit dem Typ, Webmetic-Event-Id mit der id und Webmetic-Signature. Webmetic sendet Ihre eigenen Header ebenfalls mit.
Das Beispiel ist gekürzt, und Beispiel-Ereignis liefert ein vollständiges Ereignis.
{
"id": "evt_3f9c2a71b04d8e65",
"type": "company.returned",
"created_at": "2026-10-14T08:16:02.481000Z",
"test": false,
"website": "ihre-website.de",
"data": {
"company": {
"company_id": "41ea486a9c95",
"company_name": "Bergquell Mineralbrunnen GmbH",
"company_url": "www.bergquell.example",
"company_logo_url": "https://logos.docs.example/bergquell.png",
"city": "Freising",
"country": "Deutschland",
"country_code": "DE",
"employee_count": [201, 500],
"relevance_score": 80.96,
"fit_score": 92,
"lead_score": 88.0
},
"visit": {
"timestamp": "2026-10-14T08:12:05.214000Z",
"session_id": "01M4WQFX6YM2X5V8T4N6R1C0DZ",
"weburl": "https://ihre-website.de",
"utm_source": "linkedin",
"utm_medium": "social",
"utm_campaign": "messe-2026",
"session_duration": 309.0,
"session_time": 103.0,
"session_engagement": 284.0,
"visitor_city": "Freising",
"visitor_country_code": "DE",
"user_data": [
{
"timestamp": "2026-10-14T08:12:05.214000Z",
"document_location": "https://ihre-website.de/preise?utm_source=linkedin&utm_medium=social&utm_campaign=messe-2026",
"document_title": "Preise",
"scroll_depth": 75,
"referrer": "https://www.linkedin.com/",
"time_spent": 95.0,
"engagement_time": 70,
"user_events_count": 1
}
]
},
"segment": null,
"truncated": false
}
}Signatur prüfen
Ihr System prüft mit der Signatur, ob eine Zustellung von Webmetic kommt. Der Header Webmetic-Signature hat die Form t=1792660800,v1= und danach die Signatur:
t: der Zeitpunkt des Versands in Unix-Sekunden.v1: HMAC-SHA256 übert, einen Punkt und den Body, mit Ihrem Secret als Schlüssel und als Hex in Kleinbuchstaben.
So prüfen Sie eine Zustellung:
- Lesen Sie den Body unverändert als Bytes, denn neu erzeugtes JSON passt nicht zur Signatur.
- Berechnen Sie die Signatur mit dem ganzen Secret, also mit dem Anfang
whsec_. - Vergleichen Sie das Ergebnis mit jedem
v1-Wert. Ein Treffer genügt. - Lehnen Sie Zustellungen ab, deren
tmehr als 5 Minuten von Ihrer Uhrzeit abweicht.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWebmeticSignature(header, rawBody, secret, tolerance = 300) {
let timestamp;
const signatures = [];
for (const part of header.split(",")) {
const [key, value] = part.trim().split("=");
if (key === "t") timestamp = Number(value);
if (key === "v1" && value) signatures.push(value);
}
if (!timestamp || signatures.length === 0) return false;
if (Math.abs(Date.now() / 1000 - timestamp) > tolerance) return false;
const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
return signatures.some((s) => {
const given = Buffer.from(s, "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
});
}Wenn Sie das Secret verloren haben, ersetzen Sie es im Dashboard mit Secret erneuern. Das alte Secret gilt danach noch 24 Stunden, und so lange trägt der Header zwei v1-Werte.
Zustellung beantworten
Wenn Ihr System nicht innerhalb von 10 Sekunden mit einem Statuscode 2xx antwortet, gilt die Zustellung als fehlgeschlagen. Erledigen Sie längere Arbeit erst danach, zum Beispiel über eine Warteschlange.
Bei 408, 429, jedem 5xx, Zeitüberschreitung und Verbindungsfehlern versucht Webmetic es erneut. Jeder andere 4xx-Status beendet die Zustellung ohne neuen Versuch.
Weil Webmetic keinen Weiterleitungen folgt, tragen Sie die endgültige Adresse ein.
Neue Versuche laufen bis zu 3 Tage lang, und die Abstände wachsen dabei von einer Minute auf bis zu 24 Stunden. Jeder Versuch trägt dieselbe id und eine neue Signatur.
Erkennen Sie doppelte Zustellungen deshalb an der id, und rechnen Sie nicht mit einer festen Reihenfolge der Ereignisse.
Webhook testen
- Öffnen Sie Menü > Integrationen > Webhooks.
- Klicken Sie bei Ihrem Webhook auf Testen. Webmetic sendet sofort ein Test-Ereignis und zeigt den Statuscode Ihrer Antwort.


Test-Ereignisse tragen immer die id evt_test und das erfundene Unternehmen „Beispiel GmbH“. Die API liefert ein Beispiel ohne Zustellung:
curl "https://hub.webmetic.de/webhooks/sample?event=company.returned" \
-H "Authorization: wmtc_IHR_API_SCHLUESSEL"Webhook wieder einschalten
Wenn 3 Tage lang keine Zustellung ankommt, deaktiviert Webmetic den Webhook. Die Liste zeigt dann den Status Deaktiviert, und jeder Admin Ihres Kontos erhält eine E-Mail.
Solange der Webhook deaktiviert ist, legt Webmetic für ihn keine Ereignisse an. So schalten Sie ihn wieder ein:
- Öffnen Sie Menü > Integrationen > Webhooks.
- Klicken Sie beim Webhook auf Protokoll. Das Protokoll zeigt die neuesten 50 Zustellungen mit Status, Versuchen und Antwort.


- Beheben Sie den Fehler in Ihrem System.
- Klicken Sie auf Fortsetzen. Der Webhook hat wieder den Status Aktiv.
Im Protokoll senden Sie einzelne Zustellungen mit Erneut senden noch einmal. Fortsetzen steht nur im Dashboard bereit, nicht in der API.
Mit Pausieren halten Sie einen Webhook selbst an. Webmetic sammelt die Ereignisse dann und sendet sie, sobald Sie auf Fortsetzen klicken. Ereignisse, die älter als 30 Tage sind, sendet Webmetic nicht mehr, und das Protokoll zeigt sie als Fehlgeschlagen mit Ereignis abgelaufen.
Webhook bearbeiten
- Öffnen Sie Menü > Integrationen > Webhooks.
- Klicken Sie beim Webhook auf Bearbeiten. Das Fenster Webhook bearbeiten öffnet sich.
- Ändern Sie Bezeichnung, Ereignis, Websites, Segment oder die Header unter Erweitert. Ein Header ohne neuen Wert behält seinen gespeicherten Wert.
- Klicken Sie auf Speichern.
Weil sich die URL nicht ändern lässt, legen Sie für eine neue Adresse einen neuen Webhook an.
Weil die API kein Bearbeiten anbietet, löschen Sie den Webhook dort und legen ihn neu an.
Webhook löschen
Das Löschen lässt sich nicht rückgängig machen. Webmetic sendet wartende Zustellungen nicht mehr, und das Protokoll ist nicht mehr abrufbar. Prüfen Sie vorher im Protokoll, ob noch Zustellungen warten.
- Öffnen Sie Menü > Integrationen > Webhooks.
- Klicken Sie beim Webhook auf Löschen.
- Klicken Sie innerhalb von 3 Sekunden auf Nochmals klicken. Webmetic löscht den Webhook.
Über die API löschen Sie den Webhook mit Webhook löschen.
Grenzen
- Im Dashboard legen Sie Webhooks an, solange Ihr Konto weniger als 10 hat. Über die API sind es bis zu 50, und beide Wege zählen zusammen.
- Jeder Webhook hat bis zu drei eigene Header, deren Werte Webmetic danach nicht mehr anzeigt.
- Die URL braucht
https://und eine öffentliche Adresse, aber keinen Benutzernamen und kein Passwort. - Wenn Sie später eine Website zum Konto hinzufügen, ergänzen Sie diese Website in bestehenden Webhooks mit Bearbeiten.
- Die Endpunkte unter
/webhookshaben derzeit kein Anfragelimit. Mehr dazu unter Anfragelimits.