Docs durchsuchen

Guides und API-Endpunkte durchsuchen

Referenz

Status / Webhooks

Review-/Lieferstatus live abfragen (Pull) oder per registrierter Webhook-URL empfangen (Push).

Verfügbar
GET

/v1/status/{ad_id}

Liefert den aktuellen effective_status einer Ad — live aus der Meta-API geholt und serverseitig zwischengespeichert. Bei DISAPPROVED wird der Ablehnungsgrund mitgegeben, damit die Kundenplattform ihn anzeigen und einen Retry ermöglichen kann.

Path-Parameter

NameTypPflichtBeschreibung
ad_idstring (UUID)erforderlichInterne Ad-ID (aus POST /v1/ads). z. B. 9b2e7c11-3a4d-4f88-bb20-1c6e8a5d2f90

Request · Next.js

const ad_id = "9b2e7c11-3a4d-4f88-bb20-1c6e8a5d2f90";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/status/${ad_id}`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": {
    "ad_id": "9b2e7c11-3a4d-4f88-bb20-1c6e8a5d2f90",
    "effective_status": "DISAPPROVED",
    "disapproval_reason": "Text-Overlay zu groß"
  },
  "request_id": "…"
}

effective_status ist auf ACTIVE | PAUSED | PENDING_REVIEW | DISAPPROVED | ARCHIVED normalisiert. disapproval_reason ist nur bei DISAPPROVED gesetzt, sonst null.

GET

/v1/webhooks

Listet die registrierten Webhook-Endpunkte des Kunden mit URL, abonnierten Events, Status und Zustell-Statistik (letzte Zustellung, Fehlerzähler). Das signing_secret wird NICHT zurückgegeben (nur einmalig bei der Registrierung). Scope reporting genügt.

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/webhooks`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": [
    {
      "id": "wh_5d33…",
      "url": "https://kunde.de/hooks/campaignkit",
      "events": ["ad.status_changed"],
      "status": "active",
      "last_delivery_at": "2026-06-18T10:12:00Z",
      "failure_count": 0,
      "created_at": "2026-06-01T08:00:00Z"
    }
  ],
  "request_id": "…"
}
POST

/v1/webhooks

Registriert eine HTTPS-URL, an die Statusänderungen gepusht werden (z. B. Anzeige genehmigt/abgelehnt). So muss die Kundenplattform nicht pollen. Die Antwort enthält EINMALIG ein signing_secret — damit jede Zustellung über den Header X-CampaignKit-Signature verifiziert werden kann.

Body-Parameter

NameTypPflichtBeschreibung
urlstring (URL)erforderlichHTTPS-Endpunkt der Kundenplattform (http wird abgelehnt). z. B. https://kunde.de/hooks/campaignkit
eventsstring[]optionalAbonnierte Ereignisse. Default: ["ad.status_changed"] (aktuell einziges Event). z. B. ["ad.status_changed"]

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/webhooks`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      url: "https://kunde.de/hooks/campaignkit",
      events: ["ad.status_changed"],
    }),
});
const data = await res.json();

Response 200

{
  "data": {
    "id": "wh_5d33…",
    "url": "https://kunde.de/hooks/campaignkit",
    "events": ["ad.status_changed"],
    "active": true,
    "signing_secret": "whsec_… (nur hier einmalig)"
  },
  "request_id": "…"
}

signing_secret wird nur in dieser Antwort zurückgegeben und ist danach nicht mehr abrufbar — sicher speichern. Zustellungen tragen die Header X-CampaignKit-Event, X-CampaignKit-Delivery (Dedup) und X-CampaignKit-Signature: t=<unix>,v1=<hmac>. Verifikation: HMAC-SHA256 über "<t>.<roher Body>" mit dem signing_secret bilden und mit v1 vergleichen.