Ações de webhook - Ayrshare API Documentation

Existem vários tipos de webhooks disponíveis, categorizados por tipo de ação. Por exemplo, uma publicação agendada dispara um webhook de ação scheduled. Consulte a visão geral dos webhooks para mais detalhes. Após registrar uma URL de webhook, você receberá uma requisição POST na sua URL quando um evento ocorrer. A requisição POST incluirá um payload JSON com os detalhes do evento.

Scheduled Action

Você receberá esta notificação de webhook quando uma publicação agendada for processada — seja com sucesso ou falha — e publicada nas redes sociais selecionadas. Por exemplo, se você agendar uma publicação para 12h00 de 1º de agosto de 2026, o webhook será enviado no momento exato em que a publicação for publicada. As notificações de webhook são enviadas apenas para publicações agendadas para o futuro usando o campo scheduleDate no endpoint /post.

Scheduled Event

{
  "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
}

Você não receberá notificação de webhook para publicações imediatas, pois a API retorna a resposta de sucesso ou falha instantaneamente na resposta JSON. As notificações de webhook são enviadas apenas para publicações agendadas, já que estas são processadas de forma assíncrona e exigem uma notificação separada para informar o status.

Webhook de publicação do TikTok

Ao trabalhar com o TikTok pelo Ayrshare, você pode receber dois webhooks diferentes para uma publicação agendada. Se sua publicação foi agendada em vez de imediata, você receberá primeiro o webhook padrão Scheduled Action. Isso indica que a mídia foi enviada com sucesso ao TikTok para processamento e publicação. Depois, você receberá o webhook subAction: tikTokPublished. Ele é disparado quando o TikTok conclui o processamento da mídia e a torna pública. Este webhook é ativado tanto para publicações imediatas quanto para publicações agendadas. No painel do Ayrshare, este evento aparece como tikTok (pub).

O webhook tikTokPublished não é enviado até que a mídia seja tornada pública. Se a mídia estiver definida como privada, para seguidores ou amigos, o webhook não será enviado.Se você não receber o webhook tikTokPublished e o status da publicação permanecer pending, verifique no aplicativo móvel do TikTok se a mídia foi aceita pelo TikTok.

Notificação quando o profile de um usuário vincula ou desvincula uma rede social.

{
  "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
}

Um source igual a system significa que o Ayrshare desvinculou automaticamente a conta, como quando a conexão com a rede social não é mais válida. Recomendamos que você avise o usuário para que ele possa continuar publicando. Detalhes da desvinculação aparecem no campo details. Um e-mail também será enviado para o endereço de e-mail da Conta Principal ou para os e-mails alternativos, caso tenham sido configurados. Um source igual a user significa que o usuário iniciou a ação por conta própria, como quando desvinculou manualmente uma conta. Um e-mail não será enviado quando ocorrer uma ação iniciada pelo usuário.

Messages Action

O add-on de Mensagens é necessário para acessar todos os endpoints e webhooks de mensagens. Notificação quando uma nova mensagem direta chega, é lida pelo usuário ou quando uma reação é criada ou excluída em uma mensagem — apenas para Facebook e Instagram. Webhooks de X/Twitter estão disponíveis como opção para clientes Enterprise. Entre em contato com seu representante de conta para mais informações sobre como se tornar um cliente Enterprise.

Cobertura de standby para Páginas do Facebook com múltiplos apps

O Ayrshare se inscreve no campo de webhook standby do Facebook, além dos campos padrão de mensagens. Isso significa que eventos do Messenger são entregues ao seu webhook mesmo quando outro app na mesma Página do Facebook está com controle da thread no momento — por exemplo, quando uma plataforma de chatbot está definida como o receptor principal da sua Página ou quando a Page Inbox do Meta está tratando ativamente uma conversa. Não há mudança de schema para esses eventos. Eles chegam como os mesmos payloads de messageCreated / messageRead / reactionCreated / messageEdited documentados nas seções abaixo. Duas coisas para se atentar em Páginas com um app do Messenger concorrente instalado:

O volume de mensagens de entrada pode aumentar em comparação com o comportamento anterior, quando eventos de standby eram descartados silenciosamente antes de haver assinatura. O novo tráfego representa mensagens que sua Página recebeu e que estavam sendo tratadas pelo outro app.
Você pode receber eventos messageCreated com type: "sent" que não correspondem a mensagens enviadas por você através do Ayrshare. Estes são ecos de mensagens enviadas pelo outro app do Messenger na sua Página (o Meta entrega uma cópia de cada envio para cada app assinado). Se sua integração reconcilia o tráfego de saída com o seu próprio histórico de envios, você pode usar esse histórico para distinguir seus envios dos envios de um app concorrente.

Para Páginas apenas com o Ayrshare instalado (sem app do Messenger concorrente), a única mudança observável é o novo Message Edit Event — todo o resto se comporta de forma idêntica ao anterior.

New Message Events

Notificação quando uma nova mensagem é enviada ou recebida.

{
  "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 Event

Notificação quando uma mensagem é lida pelo destinatário.

{
  "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
}

Quando uma mensagem é lida no Instagram, o payload do webhook inclui um campo mid que identifica de forma única qual mensagem específica foi lida. Para mensagens do Facebook, as leituras de mensagem são rastreadas em nível de conversa usando o conversationId. Quando ocorre um evento de leitura, todas as mensagens dessa conversa com timestamps anteriores ao timestamp created (ou read) devem ser consideradas lidas pelo usuário.

Reaction Created and Deleted Events

Notificação quando uma reação, como uma curtida, é criada ou excluída em uma mensagem.

{
  "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 Event

Notificação quando um usuário edita uma mensagem que enviou anteriormente. Disponível para mensagens diretas do Facebook e Instagram. O campo messageEdit.mid corresponde ao id do evento messageCreated original, de modo que os consumidores podem correlacionar a edição com a mensagem original. O campo messageEdit.text traz o novo texto editado da mensagem.

{
  "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

Notificação quando um batch conclui o processamento e o arquivo está disponível, como em obter todos os user profiles. Você pode acessar o arquivo com a URL pré-assinada no campo url.

Batch Event

{
  "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

Notificação quando um novo item de feed RSS é encontrado para feeds RSS registrados. Observação: se o webhook estiver ativo, novos itens de RSS não serão automaticamente publicados nas redes sociais.

Feed Event

{
    "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

Notificação quando sua conta conectada é mencionada. Disponível para Facebook e Instagram. O Ayrshare retransmite o payload nativo de menção do Meta sem alterações, adicionando apenas os campos padrão de envelope (action, refId, hookId, url e timeStamp com a Segurança de Webhook) e subAction. O exemplo abaixo é o formato do Instagram: media_id, além de comment_id quando a menção está em um comentário. Menções do Facebook chegam como a mudança nativa mention de uma Página do Meta, cujos campos diferem do exemplo do Instagram; consulte a referência de webhooks do Meta para o conjunto de campos do Facebook.

Mention Event (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

Notificação quando um comentário é criado no seu conteúdo conectado. Disponível para Facebook e Instagram. O Ayrshare retransmite o payload nativo de comentário do Meta sem alterações, adicionando apenas os campos padrão de envelope (action, refId, hookId, url e timeStamp com a Segurança de Webhook) e subAction. O exemplo abaixo é o formato do Instagram. Comentários do Facebook chegam como uma mudança de feed de uma Página, com nomes de campos diferentes (por exemplo, comment_id, post_id, message e from.name); consulte a referência de webhooks do Meta para o conjunto de campos do Facebook.

Comment Event (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

Notificação quando uma automação dispara uma ação de webhook para um usuário, como um gatilho de resposta automática de comentário ou DM.

Automation Event

{
  "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 Event

​Webhook de publicação do TikTok

​Social Action

​Social Action Event

​Messages Action

​Cobertura de standby para Páginas do Facebook com múltiplos apps

​New Message Events

​Message Read Event

​Reaction Created and Deleted Events

​Message Edit Event

​Batch Action

​Batch Event

​Feed Action

​Feed Event

​Mentions Action

​Mention Event (Instagram)

​Comments Action

​Comment Event (Instagram)

​Automations Action

​Automation Event

Scheduled Action

Scheduled Event

Webhook de publicação do TikTok

Social Action

Social Action Event

Messages Action

Cobertura de standby para Páginas do Facebook com múltiplos apps

New Message Events

Message Read Event

Reaction Created and Deleted Events

Message Edit Event

Batch Action

Batch Event

Feed Action

Feed Event

Mentions Action

Mention Event (Instagram)

Comments Action

Comment Event (Instagram)

Automations Action

Automation Event