REST APIPOST

Webhooks

Erhalten Sie signierte HTTP-Benachrichtigungen, wenn Ihre Beiträge veröffentlicht oder geplant werden, fehlschlagen oder eine Bildgenerierung fertig ist.

POSThttps://post.adaptlypost.com/post/api/v1/webhooks

Registriere einen Webhook-Endpunkt. Jeder Webhook erhält alle Ereignisse, signiert mit seinem Secret.

API-Schlüssel (Bearer-Token)

Berechtigung:webhooks.manageRollen und Berechtigungen

Webhooks erstellen, aktualisieren, löschen und testen braucht webhooks.manage (Admin und Redakteur). Webhooks auflisten und lesen braucht webhooks.read, das Mitwirkenden-Schlüssel nicht halten.

Body-Parameter

Parameter	Typ	Beschreibung
`url`ERFORDERLICH	`string`	Öffentlich erreichbarer http(s)-Endpunkt, der Ereignis-Zustellungen erhält. Private Hosts werden abgelehnt. Max. 10 Webhooks pro Workspace.

Ereignisse

Jeder registrierte Webhook erhält alle folgenden Ereignisse. Der Ereignisname wird im Payload und im x-adaptly-event-Header gesendet, sodass du auf deiner Seite filtern kannst.

Ereignis	Beschreibung
`post.published`	Alle Plattformen des Beitrags wurden erfolgreich veröffentlicht
`post.partially_failed`	Einige Plattformen veröffentlicht, andere fehlgeschlagen
`post.failed`	Veröffentlichung auf allen Plattformen fehlgeschlagen
`post.scheduled`	Ein Beitrag wurde für später geplant
`account.unauthorized`	Eine Plattform hat das Token eines Kontos abgelehnt; das Konto ist nicht autorisiert, bis es neu verbunden wird
`image.completed`	Ein mit POST /ai/images gestartetes Bild ist fertig; data.image.imageUrl ist einsatzbereit
`image.failed`	Ein mit POST /ai/images gestartetes Bild ist fehlgeschlagen; data.image.error nennt den Grund

Ereignis-Payload

Jede Zustellung ist ein JSON-Body mit id, event, createdAt und data. data enthält bei post.*-Ereignissen post, den vollständigen Beitrag in derselben Form wie GET /api/v1/social-posts/:id; bei account.unauthorized account (id, platform, displayName, pageId bei Facebook, status und die Begründung der Plattform); und bei image.*-Ereignissen image (jobId, sessionId, prompt, dann imageUrl und imageId oder error). Eine Testzustellung sendet das Ereignis webhook.test mit der Webhook-ID und der Liste der Ereignisse.

Signaturen prüfen

Jede Zustellung ist mit deinem Webhook-Secret (whsec_...) signiert. Berechne ein HMAC-SHA256 über "{timestamp}.{rawBody}" und vergleiche es mit dem x-adaptly-signature-Header, bevor du dem Payload vertraust.

Das Secret wird nur einmal angezeigt

Das Signatur-Secret (whsec_...) wird nur in der Antwort auf die Erstellungsanfrage zurückgegeben, niemals in Listen-, Abruf- oder Aktualisierungsantworten. Bewahre es sicher auf. Wenn du es verlierst, lösche den Webhook und erstelle einen neuen.

Zustellung prüfen (Node.js)

const crypto = require('crypto');

const expected =
  'sha256=' +
  crypto
    .createHmac('sha256', webhookSecret)
    .update(`${req.headers['x-adaptly-timestamp']}.${rawBody}`)
    .digest('hex');

const isValid = expected === req.headers['x-adaptly-signature'];

Zustellung und Wiederholungen

Dein Endpunkt muss innerhalb von 10 Sekunden mit 2xx antworten. Fehlgeschlagene Zustellungen werden bis zu 5-mal mit exponentiellem Backoff wiederholt. Zustellungen können mehrfach ankommen, mache deinen Handler idempotent.

Automatische Deaktivierung

Nach 20 aufeinanderfolgenden fehlgeschlagenen Zustellungen wird der Webhook automatisch deaktiviert. Reaktiviere ihn per PATCH { "active": true } oder über das Dashboard.

Webhooks verwalten

Webhooks werden mit den folgenden Endpunkten verwaltet, mit derselben API-Key-Authentifizierung:

GET    /api/v1/webhooks           # list registered webhooks
GET    /api/v1/webhooks/:id       # get one webhook
PATCH  /api/v1/webhooks/:id       # update url or active
DELETE /api/v1/webhooks/:id       # delete a webhook
POST   /api/v1/webhooks/:id/test  # send a signed webhook.test event

Du kannst Webhooks auch visuell im Dashboard auf der API-Tokens-Seite verwalten.

OpenAPI-Spezifikation

Eine maschinenlesbare OpenAPI-3.0-Spezifikation der gesamten REST-API: inklusive Webhooks und Ereignis-Payload-Schema: ist öffentlich verfügbar. Importiere sie in Make, n8n oder jedes OpenAPI-kompatible Tool.

curl https://post.adaptlypost.com/post/api/v1/openapi.json

Webhook registrieren

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/webhooks \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://your-server.com/webhook"
}'

Test-Ereignis senden

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/webhooks/<webhook-id>/test \
  --header 'Authorization: Bearer <api-key>'

Beispiel einer Ereignis-Zustellung

POST <your-url>
x-adaptly-event: post.published
x-adaptly-webhook-id: wh_abc123
x-adaptly-timestamp: 1784643600
x-adaptly-signature: sha256=3f5a...

{
  "id": "deliver-webhook-...",
  "event": "post.published",
  "createdAt": "2026-07-21T14:20:00.000Z",
  "data": {
    "post": {
      "id": "post_xyz789",
      "status": "COMPLETED",
      "recurringPostId": "rp_abc123",
      "occurrenceAt": "2026-07-21T14:19:00.000Z",
      "platforms": [
        {
          "platform": "TWITTER",
          "status": "PUBLISHED",
          "platformPostId": "1234567890",
          "publishedAt": "2026-07-21T14:19:58.000Z"
        }
      ]
    }
  }
}

POST <your-url>
x-adaptly-event: account.unauthorized

{
  "id": "deliver-webhook-...",
  "event": "account.unauthorized",
  "createdAt": "2026-09-13T09:10:00.000Z",
  "data": {
    "account": {
      "id": "conn_jkl012",
      "platform": "FACEBOOK",
      "displayName": "Your Page",
      "pageId": "123456789012345",
      "status": "unauthorized",
      "reason": "Error validating access token: Sessions for the user are not allowed because the user is not a confirmed user."
    }
  }
}

POST <your-url>
x-adaptly-event: image.completed

{
  "id": "deliver-webhook-...",
  "event": "image.completed",
  "createdAt": "2026-09-20T10:02:31.000Z",
  "data": {
    "image": {
      "jobId": "generate-image-8f2a1c40-6d3b-4e91-b7c2-0a5d9e13f846",
      "sessionId": "b31c7a44-2f19-4c85-9d60-7e2af4c81b93",
      "prompt": "a red bicycle leaning against a yellow wall, soft morning light",
      "imageUrl": "https://cdn.adaptlypost.com/ai-images/ai-studio-4c81b93.png",
      "imageId": "d7e44a10-93bc-4f27-8ae5-1b06c2f4d938"
    }
  }
}

201

{
  "id": "wh_abc123",
  "url": "https://your-server.com/webhook",
  "active": true,
  "secret": "whsec_c99807...",
  "createdAt": "2026-07-21T14:00:00.000Z",
  "updatedAt": "2026-07-21T14:00:00.000Z",
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "disabledAt": null
}