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

Registrieren Sie 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 Sie auf Ihrer Seite filtern können.

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 Ihrem Webhook-Secret (whsec_...) signiert. Berechnen Sie ein HMAC-SHA256 über "{timestamp}.{rawBody}" und vergleichen Sie es mit dem x-adaptly-signature-Header, bevor Sie dem Payload vertrauen.

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. Bewahren Sie es sicher auf. Wenn Sie es verlieren, löschen Sie den Webhook und erstellen Sie 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

Ihr 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, machen Sie Ihren Handler idempotent. Eine Zustellung an einen privaten oder internen Host wird abgelehnt und mit einem Fehler vermerkt.

Automatische Deaktivierung

Nach 20 aufeinanderfolgenden fehlgeschlagenen Zustellungen wird der Webhook automatisch deaktiviert. Reaktivieren Sie 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

Sie können Webhooks auch visuell im Dashboard auf der Seite API & KI-Agenten verwalten.

OpenAPI-Spezifikation

Eine maschinenlesbare OpenAPI-3.0-Spezifikation der gesamten REST-API: inklusive Webhooks und Ereignis-Payload-Schema: ist öffentlich verfügbar. Importieren Sie 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
}