Webhooks

Was es kann

Ereignisse:

• upload_completed – eine Plattform eines Beitrags ist fertig, mit Erfolg oder Fehler, Beitragsadresse und Ihrer request_id, job_id und external_id.
• social_account_connected – ein Konto wurde verbunden (auch durch Ihren Kunden über einen Verbindungslink).
• social_account_disconnected – ein Konto wurde entfernt.
• social_account_reauth_required – der Zugang ist abgelaufen oder wurde entzogen; das Konto muss neu verbunden werden.

Jede Anfrage ist ein JSON-POST mit diesen Headern:

• X-VA-Signature und X-Upload-Post-Signature: sha256= + HMAC-SHA256 über "<Zeitstempel>.<roher Body>" mit Ihrem Signatur-Geheimnis
• X-Upload-Post-Timestamp, X-Upload-Post-Event, X-Upload-Post-Delivery

Signatur prüfen in Node.js:

const expected = 'sha256=' + crypto.createHmac('sha256', secret)
  .update(`${req.headers['x-upload-post-timestamp']}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-va-signature']));

Grenzen

• Wiederholung: Antwortet Ihr Server nicht mit einem 2xx-Status, versuchen wir es bis zu 6-mal mit wachsendem Abstand erneut.
• Anzahl Webhooks pro Arbeitsbereich hängt vom Plan ab (1 im Test).
• Webhook-Adressen müssen öffentliche https-URLs sein; Adressen aus privaten Netzen lehnen wir ab.
• Antworten Sie schnell (innerhalb weniger Sekunden) und erledigen Sie aufwendige Arbeit danach.
• Lehnen Sie Anfragen ab, deren Zeitstempel älter als ein paar Minuten ist, um Wiederholungsangriffe zu blocken.

Einrichtung

1. Öffnen Sie in der App API & Webhooks und klicken Sie auf Neuer Webhook.
2. Tragen Sie Ihre https-Adresse ein und wählen Sie die Ereignisse (standardmäßig alle).
3. Kopieren Sie das Signatur-Geheimnis – es wird nur einmal angezeigt.
4. Klicken Sie auf Testereignis senden und prüfen Sie, ob Ihr Server es empfängt.
5. Die letzten Zustellungen mit Statuscode stehen unter dem Webhook.

Über die Upload-Post-kompatible API: POST /api/uploadposts/users/notifications mit webhook_url und webhook_events. Mehr: Hilfe zu Webhooks.

Häufige Fragen

Ich habe das Signatur-Geheimnis verloren.

Löschen Sie den Webhook und legen Sie ihn neu an, oder erneuern Sie das Geheimnis mit POST /api/uploadposts/users/webhook-secret.

Bekomme ich ein Ereignis pro Plattform oder pro Beitrag?

Ein upload_completed pro Plattform. Ein Video auf drei Plattformen sendet drei Ereignisse mit derselben request_id.

Funktionieren Webhooks mit n8n, Make oder Zapier?

Ja. Nutzen Sie deren Webhook-Trigger-Adresse als Ziel. Siehe die Seiten zu n8n, Make und Zapier.