AnmeldenKostenlose Testphase starten
easyCoexistence Offizielle APIs

Instagram-Webhook-Verifizierung: hub.challenge und X-Hub-Signature-256

Für Instagram-Webhooks braucht es einen HTTPS-Endpoint, der Metas Verifizierungs-GET beantwortet. Diese Anfrage enthält hub.mode mit dem Wert subscribe, hub.verify_token und hub.challenge. Der Endpoint prüft das Token und gibt die Challenge zurück. Danach sendet Meta POST-Anfragen mit JSON-Events, die in X-Hub-Signature-256 mit dem App-Secret signiert sind. Das geschieht, sobald die App Felder abonniert hat und jedes Konto über den subscribed_apps-Edge abonniert ist.

easyCoexistence übernimmt die Meta-Seite: Die App besteht die Verifizierung, prüft X-Hub-Signature-256, abonniert jedes verbundene Instagram-Konto für Kommentare, Nachrichten und Erwähnungen und leitet die Events an Ihren HTTPS-Endpoint weiter, signiert mit X-EC-Signature und einem Secret pro Konto.

subscribe

Der Wert hub.mode ist in Metas Verifizierungsanfrage immer enthalten.

36 hours

Zeitraum, in dem Meta eine fehlgeschlagene Benachrichtigung mit abnehmender Häufigkeit wiederholt, bevor sie verworfen wird.

15 minutes

Anzahl fehlgeschlagener Nachrichtenzustellungen, bevor Meta eine Warnung an das Entwicklerkonto sendet.

1 hour

Anzahl fehlschlagender Nachrichtenzustellungen, bevor die Warnung Webhooks Disabled erscheint und die App vom Konto abgemeldet wird.

Live

App-Modus, den Meta verlangt, bevor eine App Benachrichtigungen für die Konten ihrer Nutzer erhält.

Wie funktioniert die Einrichtung von Instagram-Webhooks?

In vier Schritten, in der Reihenfolge der Anleitung von Meta. Der Endpoint muss die Verifizierung bestehen, bevor ein Feld ausgewählt werden kann. Die App muss Live sein, um Benachrichtigungen für die Konten ihrer Nutzer zu erhalten, und für den Produktionszugang ist eine Unternehmensverifizierung erforderlich.

1EndpointAn HTTPS URL with a valid certificate answers the verification GET
2App fieldsCallback URL, verify token and fields set in the App Dashboard
3Each accountPOST /<IG_ID>/subscribed_apps turns its notifications on
4TestA dashboard test, then a real event, reach the endpoint

Was enthält die Verifizierungsanfrage?

Ein GET an die Callback-URL, der immer dann gesendet wird, wenn Webhooks im App-Dashboard konfiguriert sind. Stimmt hub.verify_token mit dem eigenen Token des Endpoints überein, lautet die Antwort 200 mit dem Wert von hub.challenge als gesamtem Body, andernfalls 403. Das Dashboard zeigt an, ob der Endpoint bestanden hat.

  • hub.mode: immer subscribe.
  • hub.challenge: eine ganze Zahl, die Meta erzeugt und die der Endpoint zurücksenden muss.
  • hub.verify_token: die Zeichenkette, die im Feld Verify Token des Dashboards eingetragen wird und nur Meta und dem Endpoint bekannt sein sollte.
  • In PHP werden die Punkte in diesen Namen zu Unterstrichen, sodass die Werte als hub_mode, hub_challenge und hub_verify_token ankommen.
The verification request and its answer
GET https://<YOUR_HOST>/webhooks/instagram
  ?hub.mode=subscribe
  &hub.challenge=1158201444
  &hub.verify_token=<YOUR_VERIFY_TOKEN>

HTTP/1.1 200 OK
Content-Type: text/plain

1158201444

Wo werden Callback und Felder festgelegt?

Im App-Dashboard unter Instagram, API setup with Instagram login, Configure webhooks: Dort tragen Sie die Callback-URL und das Verify Token ein, und beim Speichern startet die Verifizierungsanfrage. Das Produkt Instagram ist standardmäßig für comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral und messaging_seen abonniert. Über Manage lässt sich jedes davon wieder abbestellen. Die Schaltfläche Test sendet eine Beispielbenachrichtigung für ein ausgewähltes Feld.

Wie wird X-Hub-Signature-256 geprüft?

Meta signiert jede Event-Benachrichtigung mit einem HMAC-SHA256 über die Payload, geschlüsselt mit dem App-Secret, und sendet ihn in X-Hub-Signature-256 als sha256= gefolgt vom hexadezimalen Digest. Der Empfänger berechnet denselben HMAC über den rohen Body der Anfrage und vergleicht ihn zeitkonstant mit dem Header. Metas Anleitung zu Nachrichten weist darauf hin, dass sich die Signatur auf die Payload mit Unicode-Escapes bezieht. Wer dekodiertes oder neu serialisiertes JSON hasht, erhält daher ein anderes Ergebnis.

Node.js: answering verification and checking X-Hub-Signature-256
import crypto from "node:crypto";
import express from "express";

const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;

// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
  const ok = req.query["hub.mode"] === "subscribe" &&
    req.query["hub.verify_token"] === VERIFY_TOKEN;
  if (!ok) return res.sendStatus(403);
  res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});

// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
  const expected = Buffer.from(
    "sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
  );
  const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // answer first, work after
  const body = JSON.parse(req.body.toString("utf8"));
  // hand body.entry to a queue or background job
});

app.listen(3000);

Warum kann nur das App-Secret sie prüfen?

Weil die Signatur ein HMAC ist, der mit diesem Secret geschlüsselt wird. Ohne es kann niemand den erwarteten Wert berechnen, und wer eine Kopie einer Payload besitzt, kann keine gefälschte erzeugen. Die Prüfung gehört daher auf den Server, der die Anfragen von Meta für die App empfängt. Meta bittet darum, dass App-Secrets, Access-Tokens und Client-Credentials nicht in Logs oder Support-Anfragen auftauchen. Ein System, das Events empfängt, die eine andere App weitergibt, kann Metas Signatur gar nicht prüfen und stützt sich stattdessen auf die eigene Signatur dieser App.

Warum braucht jedes Konto ein eigenes Abonnement?

Weil das App-Dashboard festlegt, was die App empfangen kann, Benachrichtigungen für ein Konto aber erst beginnen, wenn auch dieses Konto abonniert ist. Bei Instagram-Login senden Sie POST /<IG_ID>/subscribed_apps an graph.instagram.com, mit dem Instagram-User-Access-Token des Kontos und subscribed_fields, der kommagetrennten Liste der für die App gewählten Felder. Ein erfolgreicher Aufruf liefert success mit dem Wert true zurück.

Subscribing one account to comments and messages
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

Was macht Meta, wenn Zustellungen fehlschlagen?

Meta wiederholt sie und gibt dann auf. Metas Anleitung verlangt für jede Benachrichtigung ein 200 OK und warnt, dass Batching mit bis zu 1,000 Updates nicht garantiert ist. Ein fehlgeschlagenes Update wird sofort wiederholt, danach noch einige Male mit abnehmender Häufigkeit über 36 Stunden und anschließend verworfen. Dasselbe Event kann daher zweimal ankommen. Für Nachrichten-Events gelten Metas Regeln zur Nachrichtenzustellung, die schneller reagieren:

  • Ein 200 OK wird innerhalb von 5 Sekunden erwartet, und eine fehlgeschlagene Zustellung wird einige Male sofort wiederholt. Deduplizieren Sie deshalb anhand der message mid.
  • Nach 15 Minuten mit Fehlern geht eine Warnung an das Entwicklerkonto.
  • Nach einer Stunde mit Fehlern folgt eine Warnung Webhooks Disabled, und die App wird von den Webhooks des Kontos abgemeldet, bis sie erneut abonniert.
  • Nachrichten, die während einer Störung gesendet wurden, können in falscher Reihenfolge ankommen. Sortieren Sie sie deshalb nach timestamp.

Was sollten Sie prüfen, wenn nichts ankommt?

Metas Checkliste zur Fehlersuche, die die meisten stummen Endpoints abdeckt, in dieser Reihenfolge:

  • Die Callback-URL hat ihre Prüfung bestanden und ist über HTTPS mit einem gültigen Zertifikat erreichbar. Selbstsignierte Zertifikate werden nicht unterstützt.
  • Die App hat das Feld gewählt und die nötige Zugriffsstufe, Advanced Access für comments und live_comments.
  • Benachrichtigungen sind für das Konto über subscribed_apps aktiviert, mit einem Token aus derselben Login-Einrichtung.
  • Das Konto erfüllt die Regeln des Feldes: Kommentarbenachrichtigungen setzen Medien voraus, die einem öffentlichen Konto gehören.
  • Der Server gibt success zurück, bevor er mit langsamer Arbeit beginnt.

Warum signiert easyCoexistence weitergeleitete Events erneut?

Weil Metas Signatur nicht weitergegeben werden kann. Die App von easyCoexistence empfängt Metas Zustellung, prüft X-Hub-Signature-256 mit dem eigenen App-Secret, antwortet Meta sofort und sendet jeden Eintrag eines verbundenen Kontos per POST an den für dieses Konto festgelegten Endpoint. Der Body ist neu aufgebaut und enthält platform, account_id, external_id und entry. Metas Header wird nicht weitergereicht, und ohne dieses Secret ließe er sich ohnehin nicht prüfen. Deshalb trägt jede Weiterleitung Content-Type: application/json und X-EC-Signature, geschlüsselt mit einem Secret, das zu genau diesem Konto gehört.

Wie prüfen Sie X-EC-Signature?

Der Header hat die Form t=<unix>,v1=<hex>. v1 ist der hexadezimale HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem rohen Body, geschlüsselt mit dem Signing-Secret des Kontos. Berechnen Sie ihn neu über die Bytes genau so, wie sie empfangen wurden, vergleichen Sie zeitkonstant, und weisen Sie einen Zeitstempel ab, der älter als 5 Minuten ist.

  • Das Secret beginnt mit whsec_ und wird einmal angezeigt, durch set_social_webhook_destination oder PUT /channels/:id/webhook, wenn die URL gesetzt wird.
  • Wird die URL erneut gesetzt, entsteht ein neues Secret. Eine URL mit dem Wert null schaltet die Weiterleitung ab.
  • Jedes Event wird einmal gesendet, mit einer Wartezeit von bis zu 8 Sekunden, ohne Weiterleitungen zu folgen, an eine HTTPS-Adresse, die auf eine öffentliche IP auflöst.
  • Wenn Sie die Verbindung entfernen, meldet das das Konto von Metas Webhooks ab und löscht Endpoint und Secret.
Python: checking X-EC-Signature
import hashlib, hmac, time

def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
    """Check X-EC-Signature on an event forwarded by easyCoexistence."""
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False  # missing, malformed or older than 5 minutes
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), v1.encode())

Häufige Fehler

  • Die Challenge als JSON oder in Anführungszeichen zurückgeben. Meta erwartet den Wert von hub.challenge selbst als Body, mit dem Status 200.
  • Einen geparsten Body hashen. Ein JSON-Parser verwirft die genauen Bytes, die Meta signiert hat. Bewahren Sie deshalb den rohen Body für den HMAC auf und parsen Sie ihn danach.
  • Die App abonnieren und das Konto vergessen. Solange POST /<IG_ID>/subscribed_apps für ein Konto nicht erfolgreich war, kommen keine Benachrichtigungen für dieses Konto an.
  • Einen Endpoint eine Stunde lang fehlschlagen lassen. Meta deaktiviert dann die Nachrichten-Webhooks und meldet die App vom Konto ab, das erneut abonniert werden muss.
Mit EasyCoexistence

Dabei wird jede Verbindung rund um die Uhr überwacht. Aktivieren Sie es mit set_social_webhook_destination oder über die Partner API. US$ 9 bis US$ 0.75 pro Verbindung und Monat, mit steigender Anzahl sinkend, die ersten 3 Tage sind eine kostenlose Testphase.

Häufig gestellte Fragen

Was ist hub.challenge bei Instagram-Webhooks?

Eine ganze Zahl, die Meta in ihrer Verifizierungs-GET sendet. Nachdem der Endpoint hub.verify_token geprüft hat, gibt er sie als Antwort-Body zurück. Damit belegt er, dass er die URL kontrolliert.

Warum fehlen hub.mode und hub.challenge in PHP?

PHP wandelt die Punkte in Parameternamen in Unterstriche um, sodass die Verifizierungswerte von Meta als hub_mode, hub_challenge und hub_verify_token ankommen.

Wie aktiviere ich Instagram-Webhooks wieder, nachdem Meta sie deaktiviert hat?

Beheben Sie den Endpoint und abonnieren Sie das Konto dann erneut mit POST /<IG_ID>/subscribed_apps und denselben Feldern.

Funktioniert ein selbstsigniertes Zertifikat für einen Instagram-Webhook-Endpoint?

Nein, Meta unterstützt selbstsignierte Zertifikate nicht. Die Callback-URL muss über HTTPS mit einem gültigen Zertifikat erreichbar sein, der erste Punkt auf Metas Checkliste zur Fehlersuche.

Weiterlesen

Verbinden Sie Ihren ersten Kanal in zwei Minuten.

Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.

  • 3 Tage kostenlos
  • Jederzeit kündbar
  • Nur offizielle APIs
  • Überwacht rund um die Uhr (24/7)

Verifiziert am