Webhook-Aktionen - Ayrshare API Documentation

Es gibt mehrere Arten von Webhooks, die nach Aktionstyp kategorisiert sind. Beispielsweise löst ein geplanter Beitrag einen scheduled-Action-Webhook aus. Weitere Details finden Sie in der Webhook-Übersicht. Nach dem Registrieren einer Webhook-URL erhalten Sie eine POST-Anfrage an Ihre URL, wenn ein Ereignis auftritt. Die POST-Anfrage enthält eine JSON-Payload mit den Ereignisdetails.

Scheduled Action

Sie erhalten diese Webhook-Benachrichtigung, wenn ein geplanter Beitrag verarbeitet wird – ob erfolgreich oder fehlgeschlagen – und in den ausgewählten sozialen Netzwerken veröffentlicht wird. Beispiel: Wenn Sie einen Beitrag für den 1. August 2026 um 12:00 Uhr planen, wird der Webhook genau zu dem Zeitpunkt gesendet, an dem der Beitrag veröffentlicht wird. Webhook-Benachrichtigungen werden nur für Beiträge gesendet, die über das Feld scheduleDate im /post-Endpunkt in der Zukunft geplant sind.

Scheduled-Ereignis

{
  "action": "scheduled", // The action taken
  "subAction": "tikTokPublished", // Only present when TikTok video publishing complete
  "created": "2023-01-05T01:18:47Z",
  "code": 200, // HTTP response code
  "refId": "140b8700bd6ade089b242d845e268fb886130c53", // User Reference ID
  "status": "success", // success or error
  "id": "TBAAAqAMMpoweA9wKHUp", // Ayrshare id of post
  "errors": [], // List of errors if any occurred
  "postIds": [
    // Individual successful posts status
    {
      "postUrl": "https://www.facebook.com/102775127855689_361718068618052",
      "platform": "facebook",
      "status": "success",
      "id": "102775127855689_361718068618052"
    }
  ],
  "url": "https://mysite.com/webhook" // Your webhook URL
}

Sie erhalten keine Webhook-Benachrichtigung für sofortige Beiträge, da die API die Erfolgs- oder Fehlerantwort sofort in der JSON-Antwort zurückgibt. Webhook-Benachrichtigungen werden nur für geplante Beiträge gesendet, da diese asynchron verarbeitet werden und eine separate Benachrichtigung erfordern, um Sie über ihren Status zu informieren.

TikTok-Publishing-Webhook

Bei der Arbeit mit TikTok über Ayrshare können Sie für einen geplanten Beitrag zwei verschiedene Webhooks erhalten. Wenn Ihr Beitrag geplant und nicht sofort veröffentlicht wurde, erhalten Sie zunächst den Standard-Scheduled-Action-Webhook. Dieser zeigt an, dass die Medien erfolgreich zur Verarbeitung und Veröffentlichung an TikTok gesendet wurden. Anschließend erhalten Sie den subAction: tikTokPublished-Webhook. Dieser wird ausgelöst, sobald TikTok die Verarbeitung der Medien abgeschlossen hat und die Medien öffentlich sind. Dieser Webhook wird sowohl für sofortige als auch für geplante Beiträge aktiviert. Im Ayrshare-Dashboard wird dieses Ereignis als tikTok (pub) bezeichnet.

Der tikTokPublished-Webhook wird erst gesendet, wenn die Medien öffentlich gemacht wurden. Wenn die Medien auf privat, „Follower“ oder „Freunde“ eingestellt sind, wird der Webhook nicht gesendet.Wenn Sie den tikTokPublished-Webhook nicht erhalten und der Beitragsstatus pending bleibt, prüfen Sie in der mobilen TikTok-App, ob die Medien von TikTok akzeptiert wurden.

Benachrichtigung, wenn ein Nutzerprofil ein soziales Netzwerk verknüpft oder trennt.

{
  "action": "social", // The action taken
  "created": "2023-01-05T01:18:47Z",
  "code": 200, // HTTP response code
  "details": {
    // Optional: if details available
    "status": "error",
    "code": 349,
    "message": "Account locked"
  },
  "displayName": "Instagram Title", // If a user account name is present at the social network
  "hookId": "TKLc30192HLGw5UeJ46",
  "platform": "instagram", // The social platform the action occured
  "refId": "140b8700bd6ade089b242d845e268fb886130c53", // User Reference ID
  "refreshBy": "2022-11-05T12:21:29Z", // Optional: If type is refresh, the date the social network authorization must be refreshed on the social account linkage page
  "source": "system", // Initiated by "system" or "user".
  "title": "User Profile Name", // The user profile's account title
  "type": "link", // Type of action: link, unlink, or refresh
  "url": "https://mysite.com/webhook" // Your webhook URL
}

Ein source-Wert system bedeutet, dass Ayrshare das Konto automatisch getrennt hat, z. B. wenn die Verbindung zum sozialen Netzwerk nicht mehr gültig ist. Wir empfehlen, den Nutzer zu informieren, damit dieser weiterhin posten kann. Details zur Trennung finden Sie im Feld details. Eine E-Mail wird zudem an die E-Mail-Adresse des Primary Accounts oder an die Alternativ-E-Mails gesendet, falls diese eingerichtet wurden. Ein source-Wert user bedeutet, dass der Nutzer die Aktion selbst ausgelöst hat, z. B. ein Konto manuell getrennt hat. Bei nutzerinitiierten Aktionen wird keine E-Mail gesendet.

Messages Action

Für den Zugriff auf alle Messages-Endpunkte und -Webhooks ist das Messaging-Add-on erforderlich. Benachrichtigung, wenn eine neue Direktnachricht eintrifft, vom Nutzer gelesen wird oder eine Reaktion auf eine Nachricht erstellt oder gelöscht wird – nur für Facebook und Instagram. X/Twitter-Webhooks sind als Option für Enterprise-Kunden verfügbar. Wenden Sie sich an Ihren Kundenbetreuer für weitere Informationen zum Enterprise-Kunden-Status.

Standby-Abdeckung für Facebook-Seiten mit mehreren Apps

Ayrshare abonniert zusätzlich zu den Standard-Messaging-Feldern das standby-Webhook-Feld von Facebook. Das bedeutet, dass Messenger-Ereignisse an Ihren Webhook geliefert werden, selbst wenn eine andere App auf derselben Facebook-Seite gerade die Thread-Kontrolle innehat – zum Beispiel wenn eine Chatbot-Plattform als primärer Empfänger Ihrer Seite eingerichtet ist oder wenn Metas Seiten-Postfach eine Konversation aktiv bearbeitet. Es gibt keine Schema-Änderung für diese Ereignisse. Sie kommen als dieselben messageCreated / messageRead / reactionCreated / messageEdited-Payloads an, die in den folgenden Abschnitten dokumentiert sind. Zwei Dinge sollten Sie für Seiten mit einer konkurrierenden Messenger-App beachten:

Das Volumen eingehender Nachrichten kann steigen gegenüber dem bisherigen Verhalten, bei dem Standby-Ereignisse stillschweigend verworfen wurden, bevor sie abonniert wurden. Der neue Traffic entspricht Nachrichten, die Ihre Seite erhalten hat und die von der anderen App bearbeitet wurden.
Sie erhalten möglicherweise messageCreated-Ereignisse mit type: "sent", die nicht Nachrichten entsprechen, die Sie über Ayrshare gesendet haben. Dies sind Echos von Nachrichten, die von der anderen Messenger-App auf Ihrer Seite gesendet wurden (Meta liefert eine Kopie jedes Sendens an jede abonnierte App). Wenn Ihre Integration ausgehenden Traffic gegen Ihren eigenen Sendeverlauf abgleicht, können Sie diesen Verlauf verwenden, um Ihre Sendungen von denen einer konkurrierenden App zu unterscheiden.

Für Seiten, auf denen nur Ayrshare installiert ist (keine konkurrierende Messenger-App), ist die einzige beobachtbare Änderung das neue Message-Edit-Ereignis – alles andere sieht identisch zum bisherigen Verhalten aus.

Neue Nachrichten-Ereignisse

Benachrichtigung, wenn eine neue Nachricht gesendet oder empfangen wird.

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "m_aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "mediaUrls": [],
  "message": "This is an amazing message",
  "platform": "facebook",
  "recipientId": "7270633706358444",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "scheduleDate": "2024-06-07T11:58:44Z",
  "senderDetails": {
    // recipientDetails if type is sent
    "id": "7270633706358444",
    "picture": "https://scontent-ord5-2.cdninstagram.com/v/t51.jpg",
    "username": "SweetMessage",
    "name": "Sweet"
  },
  "senderId": "17841452212707444",
  "subAction": "messageCreated",
  "timeStamp": 1735189325, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "received", // received, sent, or deleted
  "url": "https://mysite.com/webhook" // Your webhook URL
}

{
  "action": "messages",
  "conversationId": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6MTc4",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "mediaUrls": [],
  "message": "This is an amazing message",
  "platform": "instagram",
  "recipientId": "7270633706358444",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "scheduleDate": "2024-06-07T11:58:44Z",
  "senderDetails": {
    // recipientDetails if type is sent
    "id": "7270633706358444",
    "picture": "https://scontent-ord5-2.cdninstagram.com/v/t51.jpg",
    "username": "SweetMessage",
    "name": "Sweet"
  },
  "senderId": "17841452212707444",
  "subAction": "messageCreated",
  "timeStamp": 1735189325, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "received", // received, sent, or deleted
  "url": "https://mysite.com/webhook" // Your webhook URL
}

Message-Read-Ereignis

Benachrichtigung, wenn eine Nachricht vom Empfänger gelesen wurde.

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-08T23:33:30Z",
  "hookId": "CviPBMXEy3cdJnK0EESd",
  "platform": "facebook",
  "read": 1717889607802,  // UNIX timestamp of when the message was read
  "readerDetails": {
    "name": "John Smith",
    "id": "7101149746568444",
    "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic"
  },
  "recipientId": "106638148652329",
  "refId": "9abf1426d6ce9122ef11c8932",
  "scheduleDate": "2024-06-08T23:33:30Z",
  "senderId": "7101149746568522",
  "subAction": "messageRead",
  "timeStamp": 1717889610, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

{
  "action": "messages",
  "conversationId": "t_10161117434308938",
  "created": "2024-06-08T23:33:30Z",
  "hookId": "CviPBMXEy3cdJnK0EESd",
  "platform": "instagram",
  "read": {
    "mid": "aWdfZAG1faXRlbToxOkl" // Instagram message ID
  },
  "readerDetails": {
    "name": "John Smith",
    "id": "7101149746568444",
    "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic",
    "username": "johnsmith"
  },
  "recipientId": "106638148652329",
  "refId": "9abf1426d6ce9122ef11c8932",
  "scheduleDate": "2024-06-08T23:33:30Z",
  "senderId": "7101149746568522",
  "subAction": "messageRead",
  "timeStamp": 1717889610, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

Wenn eine Nachricht auf Instagram gelesen wird, enthält die Webhook-Payload ein mid-Feld, das eindeutig angibt, welche bestimmte Nachricht gelesen wurde. Für Facebook-Nachrichten wird das Lesen von Nachrichten auf Konversationsebene über die conversationId verfolgt. Wenn ein Read-Ereignis eintritt, sollten alle Nachrichten in dieser Konversation mit Zeitstempeln vor dem created (bzw. read)-Zeitstempel als vom Nutzer gelesen betrachtet werden.

Reaction-Created- und Reaction-Deleted-Ereignisse

Benachrichtigung, wenn eine Reaktion, z. B. ein Like, auf eine Nachricht erstellt oder gelöscht wird.

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "mediaUrls": [],
  "platform": "facebook",
  "reaction": "😮",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "scheduleDate": "2024-06-06T00:49:18Z",
  "senderId": "7101149746568444",
  "subAction": "reactionCreated", // reactionDeleted if deleted
  "timeStamp": 1717634958, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "reaction",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

{
  "action": "messages",
  "conversationId": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEO",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "mediaUrls": [],
  "platform": "instagram",
  "reaction": "😮",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "scheduleDate": "2024-06-06T00:49:18Z",
  "senderId": "7101149746568444",
  "subAction": "reactionCreated", // reactionDeleted if deleted
  "timeStamp": 1717634958, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "reaction",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

Message-Edit-Ereignis

Benachrichtigung, wenn ein Nutzer eine zuvor gesendete Nachricht bearbeitet. Verfügbar für Facebook- und Instagram-Direktnachrichten. Das Feld messageEdit.mid entspricht der id des ursprünglichen messageCreated-Ereignisses, sodass Konsumenten die Bearbeitung mit der ursprünglichen Nachricht korrelieren können. Das Feld messageEdit.text enthält den neuen, bearbeiteten Nachrichtentext.

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "id": "m_xyz...",                    // Message ID — matches the original messageCreated event
  "messageEdit": {
    "mid": "m_xyz...",
    "text": "the edited message text"
  },
  "platform": "facebook",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "senderId": "7101149746568444",
  "subAction": "messageEdited",
  "timeStamp": 1717634958,              // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "edit",
  "url": "https://mysite.com/webhook"   // Your webhook URL
}

{
  "action": "messages",
  "conversationId": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEO",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "id": "aWdfZAG1faXRlbToxOkl",
  "messageEdit": {
    "mid": "aWdfZAG1faXRlbToxOkl",
    "text": "the edited message text"
  },
  "platform": "instagram",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "senderId": "7101149746568444",
  "subAction": "messageEdited",
  "timeStamp": 1717634958,              // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "edit",
  "url": "https://mysite.com/webhook"   // Your webhook URL
}

Batch Action

Benachrichtigung, wenn ein Batch die Verarbeitung abgeschlossen hat und die Datei verfügbar ist, wie z. B. Alle User Profiles abrufen. Sie können auf die Datei mit der vorsignierten URL im Feld url zugreifen.

Batch-Ereignis

{
  "action": "batch",
  "batchType": "users",
  "created": "2024-01-11T22:00:30Z",
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "source": "user",
  "timeStamp": 1705010424, // Present with Webhook Security
  "title": "Primary Profile",
  "type": "batch",
  "url": "https://storage.googleapis.com/batch.ayrshare.com/users/dfdf92jskd933r/users-batch-2024-01-11-22-00.json",
  "urlExpires": "2024-01-18T22:00:04Z",
  "userCount": 73
}

Feed Action

Benachrichtigung, wenn ein neuer RSS-Feed-Eintrag für registrierte RSS-Feeds gefunden wird. Hinweis: Wenn der Webhook aktiv ist, werden neue RSS-Einträge nicht automatisch in den sozialen Netzwerken veröffentlicht.

Feed-Ereignis

{
    "action": "feed",
    "created": "2023-01-05T01:18:47Z",
    "code": 200,                                          // HTTP response code
    "refId": "140b8700bd6ade089b242d845e268fb886130c53",  // User Reference ID
    "title": "Title of profile if available",             // optional, only if available
    "data": { ... },
    "url": "https://api.myapp.com/Webhook/Ayrshare/Feed"  // Your webhook URL
}

Mentions Action

Benachrichtigung, wenn Ihr verbundenes Konto erwähnt wird. Verfügbar für Facebook und Instagram. Ayrshare gibt Metas native Mention-Payload unverändert weiter und ergänzt lediglich die Standard-Envelope-Felder (action, refId, hookId, url und timeStamp bei aktivierter Webhook-Sicherheit) sowie subAction. Das folgende Beispiel zeigt die Instagram-Struktur: media_id sowie comment_id, wenn die Erwähnung in einem Kommentar erfolgt. Facebook-Mentions kommen als Metas nativer mention-Change der Seite an, dessen Felder sich vom Instagram-Beispiel unterscheiden; die Facebook-Feldsätze finden Sie in Metas Webhooks-Referenz.

Mention-Ereignis (Instagram)

{
  "action": "mentions",
  "subAction": "mention",
  "media_id": "17900000000000000",    // Meta media the mention occurred on
  "comment_id": "17900000000000001",  // Present when the mention is in a comment
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Mentions"  // Your webhook URL
}

Comments Action

Benachrichtigung, wenn ein Kommentar zu Ihren verbundenen Inhalten erstellt wird. Verfügbar für Facebook und Instagram. Ayrshare gibt Metas native Kommentar-Payload unverändert weiter und ergänzt lediglich die Standard-Envelope-Felder (action, refId, hookId, url und timeStamp bei aktivierter Webhook-Sicherheit) sowie subAction. Das folgende Beispiel zeigt die Instagram-Struktur. Facebook-Kommentare kommen als Seiten-feed-Change mit anderen Feldnamen an (z. B. comment_id, post_id, message und from.name); die Facebook-Feldsätze finden Sie in Metas Webhooks-Referenz.

Comment-Ereignis (Instagram)

{
  "action": "comments",
  "subAction": "comment",
  "id": "17900000000000002",           // Comment ID
  "text": "Great post!",
  "from": {
    "id": "1234567890",
    "username": "alice"
  },
  "media": {
    "id": "17900000000000000",         // ID of the commented media
    "media_product_type": "FEED"       // e.g. FEED, REELS, STORY
  },
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Comments"  // Your webhook URL
}

Automations Action

Benachrichtigung, wenn eine Automatisierung eine Webhook-Aktion für einen Nutzer auslöst, z. B. einen Auslöser für automatische Kommentar- oder DM-Antworten.

Automation-Ereignis

{
  "action": "automations",
  "automationId": "a1B2c3D4",
  "triggerId": "t9X8y7Z6",
  "trigger": "comment_keyword",        // The trigger type that fired the automation (varies by automation)
  "platform": "instagram",
  "recipientId": "17841400000000000",
  "recipientUsername": "alice",        // null if unavailable
  "keyword": "INFO",                   // null if not keyword-triggered
  "timestamp": "2026-05-27T22:00:30Z", // When the automation fired (ISO 8601)
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Unix timestamp, present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Automations"  // Your webhook URL
}

​Scheduled Action

​Scheduled-Ereignis

​TikTok-Publishing-Webhook

​Social Action

​Social-Action-Ereignis

​Messages Action

​Standby-Abdeckung für Facebook-Seiten mit mehreren Apps

​Neue Nachrichten-Ereignisse

​Message-Read-Ereignis

​Reaction-Created- und Reaction-Deleted-Ereignisse

​Message-Edit-Ereignis

​Batch Action

​Batch-Ereignis

​Feed Action

​Feed-Ereignis

​Mentions Action

​Mention-Ereignis (Instagram)

​Comments Action

​Comment-Ereignis (Instagram)

​Automations Action

​Automation-Ereignis

Scheduled Action

Scheduled-Ereignis

TikTok-Publishing-Webhook

Social Action

Social-Action-Ereignis

Messages Action

Standby-Abdeckung für Facebook-Seiten mit mehreren Apps

Neue Nachrichten-Ereignisse

Message-Read-Ereignis

Reaction-Created- und Reaction-Deleted-Ereignisse

Message-Edit-Ereignis

Batch Action

Batch-Ereignis

Feed Action

Feed-Ereignis

Mentions Action

Mention-Ereignis (Instagram)

Comments Action

Comment-Ereignis (Instagram)

Automations Action

Automation-Ereignis