REST APIPOST

Webhooki

Otrzymuj podpisane powiadomienia HTTP, gdy posty zostają opublikowane, zaplanowane lub się nie powiodą, gdy obraz jest gotowy oraz gdy pojawią się nowe komentarze, wzmianki, wiadomości lub opinie, i weryfikuj podpis każdego ładunku.

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

Rejestruje endpoint webhooka. Pole events określa odbierane zdarzenia; pominięcie oznacza zdarzenia postów, kont i obrazów. Każde doręczenie jest podpisywane jego sekretem.

Klucz API (token Bearer)
Uprawnienie:webhooks.manageRole i uprawnienia

Tworzenie, aktualizacja, usuwanie i testowanie webhooka wymagają webhooks.manage (Administrator i Edytor). Wyświetlanie i odczyt webhooków wymagają webhooks.read, którego nie mają klucze Współtwórcy.

Parametry treści żądania

ParametrTypOpis
urlWYMAGANEstringPublicznie dostępny endpoint http(s), który będzie odbierać zdarzenia. Hosty prywatne są odrzucane. Maks. 10 webhooków na obszar roboczy.
eventsstring[]Zdarzenia odbierane przez ten webhook. Pominięcie lub [] oznacza zestaw domyślny: post.published, post.partially_failed, post.failed, post.scheduled, account.unauthorized, image.completed i image.failed. Niepusta lista dostarcza tylko wymienione zdarzenia, a zdarzenia skrzynki docierają wyłącznie po ich wymienieniu. PATCH przyjmuje to samo pole.

Zdarzenia

Webhook bez events odbiera wszystkie poniższe zdarzenia. Nazwa zdarzenia jest wysyłana w ładunku i w nagłówku x-adaptly-event.

ZdarzenieOpis
post.publishedPost opublikowano na wszystkich platformach
post.partially_failedCzęść platform opublikowała post, pozostałe zawiodły
post.failedPublikacja nie powiodła się na żadnej platformie
post.scheduledPost zaplanowano na przyszły termin
account.unauthorizedPlatforma odrzuciła token konta; konto ma status unauthorized do czasu ponownego połączenia
image.completedObraz zlecony przez POST /ai/images jest gotowy; data.image.imageUrl można już używać
image.failedGenerowanie obrazu zlecone przez POST /ai/images nie powiodło się; przyczynę podaje data.image.error

Zdarzenia skrzynki

Webhook odbiera zdarzenie skrzynki tylko wtedy, gdy jest ono wymienione w events, więc istniejące webhooki nadal otrzymują dokładnie to samo. AdaptlyPost odczytuje skrzynkę każdego konta co 10 minut, dlatego zdarzenia docierają w ciągu około 10 minut, a nie w czasie rzeczywistym.

ZdarzenieOpis
comment.createdKtoś inny skomentował jeden z postów. data.comment to komentarz w kształcie GET /api/v1/inbox/comments
comment.repliedKonto odpowiedziało na komentarz, z AdaptlyPost (panel lub API) albo z aplikacji platformy. data.comment to odpowiedź, a data.parentCommentId komentarz, na który odpowiada
mention.createdKtoś wspomniał jedno z kont. data.mention to wzmianka w kształcie GET /api/v1/inbox/mentions
message.receivedNadeszła nowa wiadomość bezpośrednia. data.conversation to rozmowa, a data.message wiadomość
review.createdNowa opinia w Google Business Profile. data.review to opinia w kształcie GET /api/v1/inbox/reviews

Brak zdarzeń dla historii

Pierwszy odczyt nowo połączonego konta i pierwszy odczyt kanału importują historię bez wysyłania zdarzeń. Zdarzenia są wysyłane tylko dla elementów znalezionych później.

Ładunek zdarzenia

Każde doręczenie to treść JSON z id, event, createdAt i data. data zawiera post, czyli cały post w kształcie GET /api/v1/social-posts/:id, dla zdarzeń post.*; account (id, platform, displayName, pageId dla Facebooka, status i przyczyna od platformy) dla account.unauthorized; image (jobId, sessionId, prompt, a następnie imageUrl i imageId lub error) dla zdarzeń image.*; comment oraz parentCommentId dla comment.replied, dla zdarzeń comment.*; mention dla mention.created; conversation i message dla message.received; oraz review dla review.created. Doręczenie testowe wysyła zdarzenie webhook.test z id webhooka i listą zdarzeń.

Weryfikacja podpisów

Każde doręczenie jest podpisane sekretem webhooka (whsec_...). Przed zaufaniem ładunkowi należy obliczyć HMAC-SHA256 z „{timestamp}.{rawBody}” i porównać go z nagłówkiem x-adaptly-signature.

Sekret jest pokazywany tylko raz

Sekret podpisu (whsec_...) jest zwracany wyłącznie w odpowiedzi na żądanie utworzenia, nigdy w odpowiedziach list, pobrania ani aktualizacji. Należy go bezpiecznie przechować. W razie utraty trzeba usunąć webhook i utworzyć nowy.
Weryfikacja doręczenia (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'];

Doręczenia i ponowienia

Endpoint musi odpowiedzieć statusem 2xx w ciągu 10 sekund. Nieudane doręczenia są ponawiane do 5 razy z wykładniczym odstępem. Doręczenia mogą dotrzeć więcej niż raz, dlatego obsługa powinna być idempotentna. Doręczenie do hosta prywatnego lub wewnętrznego jest odrzucane i zapisywane z błędem.

Automatyczne wyłączenie

Po 20 kolejnych nieudanych doręczeniach webhook jest automatycznie wyłączany. Można go włączyć ponownie przez PATCH { "active": true } lub w panelu.

Zarządzanie webhookami

Webhookami zarządza się za pomocą poniższych endpointów, z tym samym uwierzytelnianiem kluczem API:

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

Webhookami można też zarządzać w panelu, na stronie API i agenci AI.

Specyfikacja OpenAPI

Publicznie dostępna jest czytelna maszynowo specyfikacja OpenAPI 3.0 całego REST API, wraz z webhookami i schematem ładunku zdarzeń. Można ją zaimportować do Make, n8n lub dowolnego narzędzia zgodnego z OpenAPI, aby przygotować integrację.

curl https://post.adaptlypost.com/post/api/v1/openapi.json
Rejestracja webhooka
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"
}'
Rejestracja webhooka skrzynki
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/inbox-webhook",
  "events": ["comment.created", "message.received", "review.created", "post.failed"]
}'
Wysłanie zdarzenia testowego
curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/webhooks/<webhook-id>/test \
  --header 'Authorization: Bearer <api-key>'
Przykładowe doręczenie zdarzenia
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"
    }
  }
}
Przykładowe doręczenia skrzynki
POST <your-url>
x-adaptly-event: comment.created

{
  "id": "deliver-webhook-...",
  "event": "comment.created",
  "createdAt": "2026-11-08T09:20:03.000Z",
  "data": {
    "comment": {
      "id": "cmt_8f2a1c40",
      "accountId": "conn_ig_001",
      "platform": "INSTAGRAM",
      "postId": "cmm0z0k3q0000i0r5mxn0hfhs",
      "platformPostId": "18034417852490123",
      "author": { "id": "17841400000000001", "name": "Ana Souza", "username": "ana.souza", "avatarUrl": null },
      "text": "Does this work with Reels too?",
      "createdAt": "2026-11-08T09:12:44.000Z",
      "status": "UNREAD",
      "capabilities": { "canReply": true, "canHide": true, "canDelete": true, "canLike": false }
    }
  }
}

POST <your-url>
x-adaptly-event: comment.replied

{
  "id": "deliver-webhook-...",
  "event": "comment.replied",
  "createdAt": "2026-11-08T09:31:40.000Z",
  "data": {
    "comment": { "id": "cmt_9b31d7e2", "isReply": true, "isOwn": true, "text": "Yes, Reels work the same way.", "...": "..." },
    "parentCommentId": "cmt_8f2a1c40"
  }
}

POST <your-url>
x-adaptly-event: message.received

{
  "id": "deliver-webhook-...",
  "event": "message.received",
  "createdAt": "2026-11-08T09:02:15.000Z",
  "data": {
    "conversation": { "id": "cnv_5d0e7a19", "platform": "FACEBOOK", "replyWindowEndsAt": "2026-11-09T08:55:02.000Z", "...": "..." },
    "message": {
      "id": "msg_a1f20c33",
      "isOwn": false,
      "text": "Hi, do you ship to Portugal?",
      "hasAttachments": false,
      "createdAt": "2026-11-08T08:55:02.000Z"
    }
  }
}
201
{
  "id": "wh_abc123",
  "url": "https://your-server.com/webhook",
  "active": true,
  "secret": "whsec_c99807...",
  "events": [],
  "createdAt": "2026-07-21T14:00:00.000Z",
  "updatedAt": "2026-07-21T14:00:00.000Z",
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "disabledAt": null
}