> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Ações de webhook
> Ações e eventos de webhook
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](/apis/webhooks/overview) 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](/apis/post/post).
### Scheduled Event
```json theme={"system"}
{
"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](/apis/post/social-networks/tiktok#visibility-options).
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.
## Social Action
Notificação quando o profile de um usuário vincula ou desvincula uma rede social.
### Social Action Event
```json theme={"system"}
{
"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](/multiple-users/manage-user-profiles#alternative-emails-for-alerts), 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](#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.
```json Facebook New Message theme={"system"}
{
"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
}
```
```json Instagram New Message theme={"system"}
{
"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.
```json Facebook Read theme={"system"}
{
"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
}
```
```json Instagram Read theme={"system"}
{
"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.
```json Facebook Reaction theme={"system"}
{
"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
}
```
```json Instagram Reaction theme={"system"}
{
"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.
```json Facebook Message Edit theme={"system"}
{
"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
}
```
```json Instagram Message Edit theme={"system"}
{
"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](/apis/user/batch-all-users). Você pode acessar o arquivo com a URL pré-assinada no campo `url`.
### Batch Event
```json theme={"system"}
{
"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
```json theme={"system"}
{
"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)
```json theme={"system"}
{
"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)
```json theme={"system"}
{
"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
```json theme={"system"}
{
"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
}
```