> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Eventos de Webhook
> Reciba en su servidor notificación cuando Instagram envía, falla, recibe un DM, edita un mensaje o cambia el estado de conexión.
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](/es/guides/webhooks/index). Seguridad (firma HMAC): [Seguridad de Webhook](/es/guides/webhooks/seguranca).
***
## Cómo se ve el POST
```json theme={null}
{
"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
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"event": "instagram.cancelled",
"workspaceId": "clxx123...",
"instanceId": "inst_abc",
"messageId": "msg_xyz",
"timestamp": "2026-07-06T11:55:00.000Z",
"data": {
"to": "target_user",
"status": "CANCELLED"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"event": "instagram.inbound.deleted",
"workspaceId": "clxx123...",
"instanceId": "inst_abc",
"timestamp": "2026-07-06T12:17:00.000Z",
"data": {
"inboundId": "inb_abc",
"from": "sender_user"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"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](/es/instagram-api/como-funciona/quick-start): conectar y primer DM
* [Introducción](/es/instagram-api/como-funciona/introducao): ciclo de estados
* [Alcances](/es/instagram-api/como-funciona/escopos-api-key): permisos de la clave
* [Webhooks (guía general)](/es/guides/webhooks/index)