Acciones de webhook - Ayrshare API Documentation

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 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.

Evento Scheduled

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

Notificación cuando el perfil de un usuario vincula o desvincula una red 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
}

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 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 — 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.

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

Evento de mensaje leído

Notificación cuando el destinatario lee un mensaje.

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

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.

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

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.

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

Notificación cuando un batch ha terminado de procesarse y el archivo está disponible, por ejemplo obtener todos los user profiles. Puedes acceder al archivo con la URL prefirmada del campo url.

Evento Batch

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

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

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

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

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

​Evento Scheduled

​Webhook de publicación de TikTok

​Social Action

​Evento Social Action

​Messages Action

​Cobertura standby para Facebook Pages con varias apps

​Eventos de nuevo mensaje

​Evento de mensaje leído

​Eventos de reacción creada y eliminada

​Evento de edición de mensaje

​Batch Action

​Evento Batch

​Feed Action

​Evento Feed

​Mentions Action

​Evento Mention (Instagram)

​Comments Action

​Evento Comment (Instagram)

​Automations Action

​Evento Automation

Scheduled Action

Evento Scheduled

Webhook de publicación de TikTok

Social Action

Evento Social Action

Messages Action

Cobertura standby para Facebook Pages con varias apps

Eventos de nuevo mensaje

Evento de mensaje leído

Eventos de reacción creada y eliminada

Evento de edición de mensaje

Batch Action

Evento Batch

Feed Action

Evento Feed

Mentions Action

Evento Mention (Instagram)

Comments Action

Evento Comment (Instagram)

Automations Action

Evento Automation