Webhooks: das Ergebnis jedes Uploads erhalten

Webhook-Ereignisse, Inhalt, die HMAC-SHA256-Signatur-Header, ein Prüfbeispiel in Node.js, Wiederholungen und das Test-Ereignis unter API & Webhooks.

Ein Webhook ruft Ihre Adresse auf, sobald etwas passiert – ein Beitrag wurde veröffentlicht oder ist fehlgeschlagen, ein Konto wurde verbunden oder muss neu verbunden werden. Sie müssen den Status nicht mehr regelmäßig abfragen.

Webhook einrichten

1. Öffnen Sie API & Webhooks.
2. Klicken Sie unter Webhooks auf Neuer Webhook.
3. Geben Sie eine HTTPS-Adresse ein, die aus dem Internet erreichbar ist, und wählen Sie die Ereignisse.
4. Klicken Sie auf Anlegen und kopieren Sie das Signatur-Geheimnis – es wird nur einmal angezeigt.

Die Upload-Post-kompatible API bietet dasselbe: POST /api/uploadposts/users/notifications mit webhook_url und webhook_events; ein neues Geheimnis liefert POST /api/uploadposts/users/webhook-secret. Die Anzahl der Webhooks hängt von Ihrem Plan ab.

Ereignisse

Inhalt

Jede Zustellung ist ein POST mit JSON:

{
  "event": "upload_completed",
  "request_id": "2c0f…",
  "job_id": null,
  "external_id": "video-123",
  "profile_username": "meine-marke",
  "platform": "youtube",
  "media_type": "video",
  "title": "Mein Video",
  "caption": "",
  "result": { "success": true, "url": "https://www.youtube.com/watch?v=…", "post_id": "…" },
  "user_email": "inhaber@example.com",
  "created_at": "2026-11-07T12:00:03.412Z"
}

Hat die Plattform einen Hinweis gegeben (etwa YouTube hat ein Video auf privat gesetzt), steht er in result.warnings.

Signatur prüfen

Jede Zustellung hat diese Header:

• X-VA-Signature und X-Upload-Post-Signature – jeweils sha256= gefolgt vom Hex-HMAC-SHA256 über "<timestamp>.<roher Inhalt>" mit Ihrem Signatur-Geheimnis
• X-Upload-Post-Timestamp – Unix-Zeit in Sekunden
• X-Upload-Post-Event – der Name des Ereignisses

Berechnen Sie die Signatur über den rohen Inhalt der Anfrage, vor dem JSON-Parsen, und vergleichen Sie zeitkonstant. Weisen Sie alte Zeitstempel ab, um Wiederholungsangriffe zu verhindern.

// Node.js (Express): app.post('/hook', express.raw({ type: 'application/json' }), handler)
const crypto = require('crypto');

function verify(req, secret) {
  const ts = req.get('X-Upload-Post-Timestamp');
  const sig = req.get('X-VA-Signature') || req.get('X-Upload-Post-Signature') || '';
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${req.body.toString('utf8')}`).digest('hex');
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

function handler(req, res) {
  if (!verify(req, process.env.VA_WEBHOOK_SECRET)) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  // … Ihre Logik …
  res.sendStatus(200);
}

Wiederholungen

Antworten Sie innerhalb weniger Sekunden mit einem 2xx-Status. Ist Ihr Server nicht erreichbar oder antwortet mit einem Fehler, versuchen wir es bis zu 6-mal mit wachsendem Abstand erneut. Längere Arbeiten erledigen Sie besser nach der Antwort. Die letzten Zustellungen mit Statuscode und Fehler sehen Sie unter Letzte Zustellungen in API & Webhooks.

Durch Wiederholungen kann ein Ereignis zweimal ankommen. Erkennen Sie Doppelte an request_id plus platform.

Test-Ereignis senden

Klicken Sie in API & Webhooks auf Test-Ereignis senden. Jeder Webhook erhält ein upload_completed mit "test": true und einer Beispiel-YouTube-Adresse – ideal, um Ihre Signaturprüfung zu testen.

Mit n8n, Make und Zapier

Richten Sie den Webhook auf einen Webhook-Auslöser Ihres Werkzeugs (n8n-Knoten „Webhook“, Make „Custom webhook“, Zapier „Catch Hook“). Beispiele stehen auf den Seiten zu n8n, Make und Zapier sowie auf der Webhook-Integrationsseite.