Eventos de Webhook

Con la API usted pregunta; con webhooks Notifique le avisa. Ideal para bandeja en tiempo real, sincronizar ediciones o reaccionar cuando cae la sesión, sin polling.

En resumen

Cada entrega es un POST application/json a su URL registrada.
Los eventos instagram.* son solo Instagram; WhatsApp usa message.*, Telegram usa telegram.*.
instanceId identifica la conexión de Instagram.
Habilite solo los eventos que necesite su integración.
Responda 2xx rápido; el procesamiento pesado va a su cola.

Configuración general: Webhooks. Seguridad (firma HMAC): Seguridad de Webhook.

Cómo se ve el POST

{
  "event": "instagram.sent",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:00:00.000Z",
  "data": {
    "to": "target_user",
    "type": "TEXT",
    "status": "SENT",
    "sentAt": "2026-07-06T12:00:00.000Z",
    "externalId": "340282366841710301244259849902874331233"
  }
}

Campo	Descripción
`event`	Nombre del evento (ej.: `instagram.sent`)
`workspaceId`	ID del Workspace
`instanceId`	ID de la instance de Instagram
`messageId`	ID del mensaje (cuando aplique)
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos específicos del evento

Headers: X-Notifique-Signature, X-Notifique-Timestamp, X-Workspace-Id, X-Webhook-Event.

Qué debe devolver su servidor

Respuesta	Efecto
2xx en ~10s	Evento entregado; removido de la cola
4xx / 5xx / timeout	Reintento automático (5 min, 30 min, 2 h)

¿Procesamiento lento? Devuelva 200 de inmediato y procese en segundo plano.

Referencia de eventos

Mensajes que usted envía

Evento	Cuándo se dispara	Qué hacer con él
`instagram.sent`	DM aceptado por Instagram	Marcar como enviado
`instagram.delivered`	Entrega detectada en sincronización	Actualizar estado
`instagram.read`	Lectura detectada	Métricas
`instagram.responded`	El destinatario respondió	Flujo conversacional
`instagram.edited`	Texto cambiado vía API o panel	Sincronizar contenido
`instagram.deleted`	Deshacer envío (eliminado para todos)	Quitar del historial
`instagram.failed`	Falló tras reintentos	Alertar / reintentar
`instagram.cancelled`	Cola o programación cancelada	Actualizar estado

Mensajes que usted recibe

Evento	Cuándo se dispara	Qué hacer con él
`instagram.received`	Nuevo DM en bandeja sincronizada	Bot, soporte
`instagram.inbound.edited`	El remitente editó el mensaje	Sincronizar conversación
`instagram.inbound.deleted`	El remitente eliminó el mensaje	Actualizar historial

Conexión (instance)

Evento	Cuándo se dispara	Qué hacer con él
`instagram.instance.connected`	Sesión ok, ACTIVE	Habilitar envíos
`instagram.instance.disconnected`	Sesión perdida	Pausar envíos, alertar
`instagram.instance.challenge_required`	Desafío de seguridad de Instagram	Completar verificación

Payload por evento

instagram.sent

{
  "event": "instagram.sent",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:00:00.000Z",
  "data": {
    "to": "target_user",
    "type": "TEXT",
    "status": "SENT",
    "sentAt": "2026-07-06T12:00:00.000Z",
    "externalId": "340282366841710301244259849902874331233"
  }
}

instagram.delivered

{
  "event": "instagram.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:01:00.000Z",
  "data": {
    "to": "target_user",
    "status": "DELIVERED",
    "deliveredAt": "2026-07-06T12:01:00.000Z"
  }
}

instagram.read

{
  "event": "instagram.read",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:02:00.000Z",
  "data": {
    "to": "target_user",
    "status": "READ",
    "readAt": "2026-07-06T12:02:00.000Z"
  }
}

instagram.responded

{
  "event": "instagram.responded",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:05:00.000Z",
  "data": {
    "to": "target_user",
    "status": "RESPONDED",
    "respondedAt": "2026-07-06T12:05:00.000Z"
  }
}

instagram.edited

{
  "event": "instagram.edited",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:03:00.000Z",
  "data": {
    "to": "target_user",
    "status": "EDITED",
    "newContent": "Corrected text",
    "previousContent": "Original text",
    "threadId": "thread_abc",
    "source": "api"
  }
}

instagram.deleted

{
  "event": "instagram.deleted",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:10:00.000Z",
  "data": {
    "to": "target_user",
    "status": "DELETED",
    "deletedAt": "2026-07-06T12:10:00.000Z"
  }
}

instagram.failed

{
  "event": "instagram.failed",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:00:30.000Z",
  "data": {
    "to": "target_user",
    "status": "FAILED",
    "failedAt": "2026-07-06T12:00:30.000Z",
    "errorMessage": "user_not_reachable"
  }
}

instagram.cancelled

{
  "event": "instagram.cancelled",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T11:55:00.000Z",
  "data": {
    "to": "target_user",
    "status": "CANCELLED"
  }
}

instagram.received

{
  "event": "instagram.received",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "timestamp": "2026-07-06T12:15:00.000Z",
  "data": {
    "inboundId": "inb_abc",
    "from": "sender_user",
    "type": "TEXT",
    "bodyPreview": "Hi, I need help",
    "receivedAt": "2026-07-06T12:15:00.000Z"
  }
}

instagram.inbound.edited

{
  "event": "instagram.inbound.edited",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "timestamp": "2026-07-06T12:16:00.000Z",
  "data": {
    "inboundId": "inb_abc",
    "from": "sender_user",
    "newContent": "Hi, I need urgent help",
    "previousContent": "Hi, I need help"
  }
}

instagram.inbound.deleted

{
  "event": "instagram.inbound.deleted",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "timestamp": "2026-07-06T12:17:00.000Z",
  "data": {
    "inboundId": "inb_abc",
    "from": "sender_user"
  }
}

instagram.instance.connected

{
  "event": "instagram.instance.connected",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "timestamp": "2026-07-06T10:00:00.000Z",
  "data": {
    "status": "ACTIVE",
    "username": "your_username",
    "message": "Session connected"
  }
}

instagram.instance.disconnected

{
  "event": "instagram.instance.disconnected",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "timestamp": "2026-07-06T18:00:00.000Z",
  "data": {
    "status": "DISCONNECTED",
    "disconnectReason": "login_required",
    "message": "Sesión perdida; reconnect required"
  }
}

instagram.instance.challenge_required

{
  "event": "instagram.instance.challenge_required",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "timestamp": "2026-07-06T10:05:00.000Z",
  "data": {
    "status": "PENDING",
    "challenge": {
      "step_name": "verify_code"
    },
    "message": "Complete security challenge"
  }
}

Próximos pasos

Inicio rápido: conectar y primer DM
Introducción: ciclo de estados
Alcances: permisos de la clave
Webhooks (guía general)

​En resumen

​Cómo se ve el POST

​Qué debe devolver su servidor

​Referencia de eventos

​Mensajes que usted envía

​Mensajes que usted recibe

​Conexión (instance)

​Payload por evento

​Próximos pasos

En resumen

Cómo se ve el POST

Qué debe devolver su servidor

Referencia de eventos

Mensajes que usted envía

Mensajes que usted recibe

Conexión (instance)

Payload por evento

Próximos pasos