Webhooks

Ein Webhook ist eine Nachricht, die Argorant an eine Adresse auf deinem eigenen Server schickt, wenn in deinem Konto etwas passiert. Statt die API immer wieder zu fragen, ob ein Export fertig ist oder eine Antwort kam, wird dein Server benachrichtigt. Nutze das, um dein CRM zu aktualisieren, etwas in einen Team-Chat zu posten oder eine Automatisierung in n8n, Zapier oder Make zu starten. Webhooks gibt es ab dem Pro-Plan.

Einen Webhook hinzufügen

1. Öffne Einstellungen, dann API-Schlüssel und scroll zu Webhooks.
2. Gib unter Neuer Webhook deine Adresse in das URL-Feld ein. Sie muss mit https:// beginnen und aus dem Internet erreichbar sein.
3. Klick die Events an, die du willst. Ein gewähltes Event zeigt einen Haken. Mindestens eins ist nötig.
4. Klick auf Webhook hinzufügen.
5. Ein Kasten Webhook erstellt zeigt das Signatur-Secret, das mit whsec_ beginnt. Klick auf Kopieren und leg es zu den anderen Secrets deines Servers. Es wird nur einmal angezeigt.
6. Klick in der neuen Zeile auf Test senden und dann auf Zustellungen, um zu sehen, ob er angekommen ist.

Enthält dein Plan keine Webhooks, öffnet Webhook hinzufügen stattdessen die Upgrade-Ansicht.

Events

Kampagnen-Events gehen an die Webhooks aller Mitglieder des Workspace, dem die Kampagne gehört.

So sieht eine Zustellung aus

Jede Zustellung ist ein POST mit JSON-Body und diesen Headern:

Content-Type: application/json
User-Agent: Argorant-Webhooks/1.0
X-Argorant-Event: reply.positive
X-Argorant-Delivery: 903
X-Argorant-Signature: sha256=5d1c0e…

Der Body hat immer dieselben vier Felder. data hängt vom Event ab:

{
  "event": "reply.positive",
  "delivery_id": "903",
  "created_at": "2026-10-21T09:42:09.512340+00:00",
  "data": {
    "classification": "interested",
    "lead_email": "anna@northwind-supply.example",
    "campaign_id": "3f6c1a2e-8b1d-4c55-9a0e-2d7f4b1c9e10",
    "subject": "Re: Kurze Frage, Anna",
    "snippet": "Klingt gut. Passt dir Donnerstag?"
  }
}

{
  "event": "export.ready",
  "delivery_id": "904",
  "created_at": "2026-10-21T09:35:01.104220+00:00",
  "data": {
    "job_id": 84213,
    "status": "done",
    "total_rows": 500,
    "verified_rows": 482,
    "status_api_path": "/api/mcp/exports/84213",
    "download_api_path": "/api/mcp/exports/84213/download"
  }
}

Eine Zustellung über Test senden nutzt das erste Event des Webhooks und trägt {"test": true, "event": "…", "message": "Argorant webhook test delivery"} als data. So kann dein Code sie von einer echten unterscheiden.

Prüfen, ob eine Zustellung von Argorant kommt

X-Argorant-Signature ist sha256= gefolgt vom hexadezimalen HMAC-SHA256 des rohen Request-Bodys, gebildet mit deinem Signatur-Secret. Berechne denselben Wert auf deiner Seite und vergleiche. Nimm den Body genau so, wie er ankam, vor jedem JSON-Parsen, sonst passt die Signatur nicht.

// Node.js (Express)
const crypto = require("crypto");
app.post("/argorant", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", process.env.ARGORANT_WEBHOOK_SECRET)
    .update(req.body).digest("hex");
  const got = req.get("X-Argorant-Signature") || "";
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  res.sendStatus(200);          // schnell antworten, die Arbeit danach erledigen
});

# Python (Flask)
import hmac, hashlib, os
@app.post("/argorant")
def argorant():
    raw = request.get_data()
    expected = "sha256=" + hmac.new(os.environ["ARGORANT_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Argorant-Signature", "")):
        return "", 401
    return "", 200

Antworten, Wiederholungen und Abschalten

• Jede Antwort mit 2xx gilt als zugestellt. Antworte innerhalb von 10 Sekunden und erledige langsame Arbeit erst danach.
• Alles andere, ein Timeout oder eine Weiterleitung gilt als fehlgeschlagen. Weiterleitungen werden nie verfolgt, nutze also die endgültige Adresse.
• Eine fehlgeschlagene Zustellung wird nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden erneut versucht. Nach 6 Versuchen bleibt sie fehlgeschlagen.
• Nach 50 Fehlschlägen in Folge wird der Webhook abgeschaltet und als Pausiert angezeigt. Bring deinen Server in Ordnung und klick auf Fortsetzen; das setzt auch den Fehlerzähler zurück.
• Dasselbe Event kann dich zweimal erreichen, etwa nach einer Wiederholung. Nutze delivery_id (auch in X-Argorant-Delivery), um bereits verarbeitete zu überspringen.

Die Zeile jedes Webhooks zeigt seine Events, den Zeitpunkt unter Letzter Erfolg und Fehler der letzten Zeit mit dem letzten Fehlertext. Zustellungen listet die letzten 25 Zustellungen mit Event, Zeit und Ergebnis, etwa Zugestellt, Zugestellt, 2 Versuche, ausstehend oder fehlgeschlagen.

Einen Webhook verwalten

• Pausieren stoppt Zustellungen, ohne etwas zu löschen. Fortsetzen startet sie wieder. Test senden geht nur, solange der Webhook aktiv ist.
• Löschen entfernt den Webhook samt Zustellverlauf nach einer Rückfrage.
• Unter Einstellungen, dann Workspace, gibt es im Gefahrenbereich Alle Webhooks löschen.

Über die API und die CLI

Dieselben Webhooks kannst du mit einem API-Schlüssel verwalten. Über die API braucht der Schlüssel die Berechtigung, Listen zu verwalten; Schlüssel aus den Einstellungen haben sie.

curl -s https://app.argorant.com/api/v1/webhooks \
  -H "Authorization: Bearer $ARGORANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/argorant", "events": ["reply.positive", "export.ready"]}'

npx argorant webhooks add https://hooks.example.com/argorant --events reply.positive,export.ready
npx argorant webhooks                 # deine Webhooks und alle wählbaren Events
npx argorant webhooks test 41
npx argorant webhooks deliveries 41
npx argorant webhooks set 41 --inactive
npx argorant webhooks rm 41 --yes

Der Aufruf zum Anlegen liefert das secret genau einmal, wie die Einstellungsseite.

Limits

• Bis zu 10 Webhooks pro Konto, pausierte mitgezählt.
• Die Adresse muss mit https:// beginnen, darf höchstens 2.048 Zeichen lang sein und muss auf eine öffentliche Internetadresse zeigen. Private Netze, lokale Adressen und Argorants eigene Dienste werden abgelehnt.
• Webhooks sind ab dem Pro-Plan enthalten.

Häufige Fehler

• Die Adresse wird beim Hinzufügen abgelehnt. Du siehst dann eine dieser Meldungen (sie erscheinen auf Englisch).

  The webhook address must be a public internet address on your own server. Private networks, local addresses and our own services can't receive webhooks.

  We could not find a public internet address for this webhook. Check the address and try again.

  Nutze eine öffentliche HTTPS-Adresse. Zum Testen auf deinem Laptop hilft ein Tunnel-Dienst, der dir eine öffentliche HTTPS-Adresse gibt.
• Die Signatur passt nie. Dein Framework hat das JSON geparst, bevor du den HMAC berechnet hast. Bilde ihn über die rohen Bytes.
• Zustellungen scheitern an einer Weiterleitung. Die Adresse antwortet mit 301 oder 302, etwa von http auf https oder wegen eines fehlenden Schrägstrichs. Trag die endgültige Adresse ein.
• Das Secret ist verloren. Es lässt sich nicht erneut anzeigen. Lösch den Webhook und leg ihn neu an, dann bekommst du ein neues Secret.
• Es kommen keine Events an. Prüf, ob der Webhook Aktiv ist, ob du die richtigen Events gewählt hast und ob wirklich etwas passiert ist. Test senden zeigt, ob der Weg zu deinem Server funktioniert.

Wie es weitergeht

Sobald Zustellungen als Zugestellt erscheinen, verbinde die Events mit deinem Ablauf. Ein häufiges Muster: export.ready startet einen Download und einen Import in dein CRM. Passend dazu: API-Schlüssel und die REST-API und n8n.