Eventos dos Webhooks

Na API você pergunta; no webhook a Notifique avisa. Ideal para inbox em tempo real, sincronizar edições ou reagir quando a sessão cair, sem polling.

Em poucas palavras

Toda entrega é um POST application/json para a URL cadastrada.
Eventos instagram.* são só Instagram, WhatsApp usa message.*, Telegram usa telegram.*.
instanceId identifica a conexão Instagram.
Ative só os eventos que sua integração usa.
Responda 2xx rápido; processamento pesado vai para fila no seu lado.

Configuração geral: Webhooks. Segurança (assinatura HMAC): Segurança de webhooks.

Como vem o POST

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

Campo	Descrição
`event`	Nome do evento (ex.: `instagram.sent`)
`workspaceId`	ID do workspace
`instanceId`	ID da instância Instagram
`messageId`	ID da mensagem (quando aplicável)
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos específicos do evento

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

O que seu servidor deve responder

Resposta	Efeito
2xx em até ~10s	Evento entregue; sai da fila
4xx / 5xx / timeout	Retentativa automática (5 min, 30 min, 2 h)

Processamento demorado? Responda 200 logo e processe em background.

Referência por evento

Mensagens que você envia

Evento	Quando dispara	O que fazer com isso
`instagram.sent`	DM aceita pelo Instagram	Marcar como enviado
`instagram.delivered`	Entrega detectada na sincronização	Atualizar status
`instagram.read`	Leitura detectada	Métricas
`instagram.responded`	Destinatário respondeu	Fluxo conversacional
`instagram.edited`	Texto alterado via API ou painel	Sincronizar conteúdo
`instagram.deleted`	Unsend (apagou para todos)	Remover do histórico
`instagram.failed`	Falha após tentativas	Alertar / retentar
`instagram.cancelled`	Fila ou agendamento cancelados	Atualizar status

Mensagens que você recebe

Evento	Quando dispara	O que fazer com isso
`instagram.received`	Novo DM na inbox sincronizada	Bot, atendimento
`instagram.inbound.edited`	Remetente editou a mensagem	Sincronizar conversa
`instagram.inbound.deleted`	Remetente apagou a mensagem	Atualizar histórico

Conexão (instância)

Evento	Quando dispara	O que fazer com isso
`instagram.instance.connected`	Sessão ok, ACTIVE	Liberar envios
`instagram.instance.disconnected`	Sessão perdida	Pausar envios, alertar
`instagram.instance.challenge_required`	Desafio de segurança do Instagram	Completar verificação

Payload de cada evento

instagram.sent

{
  "event": "instagram.sent",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "messageId": "msg_xyz",
  "timestamp": "2026-07-06T12:00:00.000Z",
  "data": {
    "to": "usuario_alvo",
    "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": "usuario_alvo",
    "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": "usuario_alvo",
    "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": "usuario_alvo",
    "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": "usuario_alvo",
    "status": "EDITED",
    "newContent": "Texto corrigido",
    "previousContent": "Texto original",
    "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": "usuario_alvo",
    "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": "usuario_alvo",
    "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": "usuario_alvo",
    "status": "CANCELLED"
  }
}

instagram.received

{
  "event": "instagram.received",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "timestamp": "2026-07-06T12:15:00.000Z",
  "data": {
    "inboundId": "inb_abc",
    "from": "usuario_remetente",
    "type": "TEXT",
    "bodyPreview": "Oi, preciso de ajuda",
    "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": "usuario_remetente",
    "newContent": "Oi, preciso de ajuda urgente",
    "previousContent": "Oi, preciso de ajuda"
  }
}

instagram.inbound.deleted

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

instagram.instance.connected

{
  "event": "instagram.instance.connected",
  "workspaceId": "clxx123...",
  "instanceId": "inst_abc",
  "timestamp": "2026-07-06T10:00:00.000Z",
  "data": {
    "status": "ACTIVE",
    "username": "seu_usuario",
    "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": "Session lost; 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 passos

Quick Start: conectar e primeiro DM
Introdução: ciclo de status
Escopos: permissões da chave
Webhooks (guia geral)

​Em poucas palavras

​Como vem o POST

​O que seu servidor deve responder

​Referência por evento

​Mensagens que você envia

​Mensagens que você recebe

​Conexão (instância)

​Payload de cada evento

​Próximos passos

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Referência por evento

Mensagens que você envia

Mensagens que você recebe

Conexão (instância)

Payload de cada evento

Próximos passos