> ## 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.
# Acciones de webhook
> Acciones y eventos de webhook
Hay varios tipos de webhooks disponibles, categorizados por tipo de Action.
Por ejemplo, un scheduled post disparará un webhook con la acción `scheduled`.
Consulta la [visión general de webhooks](/apis/webhooks/overview) para más detalles.
Después de registrar una URL de webhook, recibirás una solicitud POST a tu URL cuando ocurra un evento.
La solicitud POST incluirá un payload JSON con los detalles del evento.
## Scheduled Action
Recibirás esta notificación de webhook cuando se procese un scheduled post — tanto si tiene éxito como si falla — y se publique en las redes sociales seleccionadas.
Por ejemplo, si programas un post para el 1 de agosto de 2026 a las 12:00 PM, el webhook se enviará exactamente en el momento en que el post se publique.
Las notificaciones de webhook solo se envían para posts programados en el futuro usando el campo `scheduleDate` en el endpoint [/post](/apis/post/post).
### Evento Scheduled
```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
}
```
No recibirás una notificación de webhook para posts inmediatos, porque la API devuelve la respuesta de éxito o error al instante en el JSON de la respuesta.
Las notificaciones de webhook solo se envían para scheduled posts, ya que se procesan de forma asíncrona y requieren una notificación aparte para informarte de su estado.
### Webhook de publicación de TikTok
Cuando trabajas con TikTok a través de Ayrshare, puedes recibir dos webhooks distintos para un scheduled post.
Si tu post fue programado en lugar de inmediato, primero recibirás el webhook estándar de **Scheduled Action**.
Esto indica que el archivo multimedia se ha enviado correctamente a TikTok para su procesamiento y publicación.
Posteriormente, recibirás el webhook `subAction: tikTokPublished`.
Se dispara una vez que TikTok ha completado el procesamiento del contenido y este se ha hecho público.
Este webhook se activa tanto para posts inmediatos como para scheduled posts.
En el dashboard de Ayrshare, este evento aparece etiquetado como **tikTok (pub)**.
El webhook `tikTokPublished` no se envía hasta que el [contenido se hace público](/apis/post/social-networks/tiktok#visibility-options).
Si el contenido se configura como privado, para seguidores o para amigos, el webhook no se enviará.
Si no recibes el webhook `tikTokPublished` y el estado del post permanece como `pending`, comprueba la app móvil de TikTok para asegurarte de que el contenido ha sido aceptado por TikTok.
## Social Action
Notificación cuando el perfil de un usuario vincula o desvincula una red social.
### Evento Social Action
```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
}
```
Un `source` con valor `system` significa que Ayrshare desvinculó la cuenta automáticamente, por ejemplo cuando la conexión con la red social ya no es válida. Recomendamos que notifiques a tu usuario para que pueda seguir publicando. Los detalles de la desvinculación se encuentran en el campo `details`. También se enviará un correo a la dirección del Primary Account, o a los [correos alternativos](/multiple-users/manage-user-profiles#alternative-emails-for-alerts) si se han configurado.
Un `source` con valor `user` significa que fue el propio usuario quien inició la acción, por ejemplo desvinculando manualmente una cuenta. No se enviará ningún correo cuando la acción sea iniciada por el usuario.
## Messages Action
Se requiere el Messaging Add-On para acceder a todos los endpoints y webhooks de messages.
Notificación cuando llega un nuevo direct message, cuando el usuario lo lee o cuando se crea o elimina una reacción sobre un mensaje. Solo para Facebook e Instagram.
Los webhooks de X/Twitter están disponibles como opción para clientes Enterprise.
Contacta con tu representante de cuenta para más información sobre cómo convertirte en cliente Enterprise.
### Cobertura standby para Facebook Pages con varias apps
Ayrshare se suscribe al campo de webhook `standby` de Facebook además de los campos estándar de messaging. Esto significa que los eventos de Messenger se entregan a tu webhook **incluso cuando otra app en la misma Facebook Page tiene el control del hilo en ese momento** — por ejemplo, cuando una plataforma de chatbot está configurada como receptor principal de tu Page, o cuando el Page Inbox de Meta está gestionando activamente una conversación.
No hay cambios en el esquema para estos eventos. Llegan como los mismos payloads `messageCreated` / `messageRead` / `reactionCreated` / `messageEdited` documentados en las secciones siguientes. Dos aspectos a tener en cuenta para Pages con una app de Messenger competidora instalada:
* **El volumen de mensajes entrantes puede aumentar** en comparación con el comportamiento anterior, en el que los eventos standby se descartaban silenciosamente antes de suscribirse a ellos. El nuevo tráfico representa mensajes que tu Page recibía y que estaba gestionando la otra app.
* **Puedes recibir eventos `messageCreated` con `type: "sent"` que no correspondan a mensajes enviados a través de Ayrshare.** Son ecos de mensajes enviados por la otra app de Messenger en tu Page (Meta entrega una copia de cada envío a todas las apps suscritas). Si tu integración reconcilia el tráfico saliente con tu propio historial de envíos, puedes usar ese historial para distinguir tus envíos de los de una app competidora.
Para Pages con solo Ayrshare instalado (sin app de Messenger competidora), el único cambio observable es el nuevo [Message Edit Event](#message-edit-event) — todo lo demás se ve idéntico al comportamiento anterior.
### Eventos de nuevo mensaje
Notificación cuando se envía o recibe un nuevo mensaje.
```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
}
```
### Evento de mensaje leído
Notificación cuando el destinatario lee un mensaje.
```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
}
```
Cuando se lee un mensaje en Instagram, el payload del webhook incluye un campo `mid` que identifica de forma única qué mensaje concreto se leyó.
Para los mensajes de Facebook, las lecturas de mensajes se rastrean a nivel de conversación usando el `conversationId`.
Cuando se produce un evento de lectura, todos los mensajes de esa conversación con timestamps anteriores al timestamp de `created` (o `read`) deben considerarse leídos por el usuario.
### Eventos de reacción creada y eliminada
Notificación cuando se crea o se elimina una reacción, como un like, sobre un mensaje.
```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
}
```
### Evento de edición de mensaje
Notificación cuando un usuario edita un mensaje que envió previamente. Disponible para direct messages de Facebook e Instagram.
El campo `messageEdit.mid` coincide con el `id` del evento `messageCreated` original, de modo que los consumidores pueden correlacionar la edición con el mensaje original. El campo `messageEdit.text` contiene el nuevo texto editado del mensaje.
```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
Notificación cuando un batch ha terminado de procesarse y el archivo está disponible, por ejemplo [obtener todos los user profiles](/apis/user/batch-all-users). Puedes acceder al archivo con la URL prefirmada del campo `url`.
### Evento Batch
```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
Notificación cuando se encuentra un nuevo elemento de un RSS feed para los RSS feeds registrados. Nota: si el webhook está activo, los nuevos elementos RSS no se publicarán automáticamente en las redes sociales.
### Evento Feed
```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
Notificación cuando se menciona tu cuenta conectada. Disponible para Facebook e Instagram.
Ayrshare retransmite sin cambios el payload nativo de menciones de Meta, añadiendo únicamente los campos del sobre estándar (`action`, `refId`, `hookId`, `url` y `timeStamp` con Webhook Security) y `subAction`. El siguiente ejemplo corresponde al formato de **Instagram**: `media_id`, más `comment_id` cuando la mención está en un comentario. Las menciones de **Facebook** llegan como el cambio nativo de `mention` de una Page de Meta, cuyos campos difieren del ejemplo de Instagram; consulta la referencia de webhooks de Meta para conocer el conjunto de campos de Facebook.
### Evento Mention (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
Notificación cuando se crea un comentario en tu contenido conectado. Disponible para Facebook e Instagram.
Ayrshare retransmite sin cambios el payload nativo de comentarios de Meta, añadiendo únicamente los campos del sobre estándar (`action`, `refId`, `hookId`, `url` y `timeStamp` con Webhook Security) y `subAction`. El siguiente ejemplo corresponde al formato de **Instagram**. Los comentarios de **Facebook** llegan como un cambio de `feed` de una Page con nombres de campo diferentes (por ejemplo `comment_id`, `post_id`, `message` y `from.name`); consulta la referencia de webhooks de Meta para conocer el conjunto de campos de Facebook.
### Evento Comment (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
Notificación cuando una automatización dispara una acción de webhook para un usuario, como un disparador de respuesta automática a comentarios o DM.
### Evento Automation
```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
}
```