Eventos de webhook - Bridge REST Integrations API & Webhooks

Os webhooks do Bridge entregam payloads estruturados em JSON sempre que ações específicas ocorrem no workspace. Cada evento segue um esquema consistente para facilitar a interpretação e a validação.

Estrutura comum dos eventos

O exemplo abaixo ilustra o envelope comum; "string" representa um tipo, não um valor de evento para enviar. Leia os exemplos específicos de cada família a seguir. Não presuma que eventId seja globalmente único entre famílias de notificação.

{
  "eventId": "string",
  "eventType": "string",
  "entity": "string",
  "workspaceId": "string",
  "timestamp": "string",
  "payload": {}
}

Notificações de resumo de conversa

v1 Disparadas uma vez por dia, por conversa, quando a IA do Bridge gera o resumo diário. O resumo reúne os principais pontos da troca de mensagens e os participantes internos e externos envolvidos.

Tipos de evento
Exemplo de payload

Tipo de evento	Descrição
`conversation_summary.created`	Um resumo diário da conversa foi gerado

{
  "eventId": "evt_summary_001",
  "eventType": "conversation_summary.created",
  "entity": "conversation_summary",
  "workspaceId": "ws_123",
  "timestamp": "2026-05-19T05:03:15.910Z",
  "payload": {
    "conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "summaryDate": "2026-05-19",
    "summary": "- Advisor asked the customer about their preferred schedule and offered to book a product demo.\n- Customer replied they are unavailable on Monday morning.\n- Advisor offered alternative slots later in the week and is waiting for confirmation.",
    "externalUsers": [
      { "id": "c1d2e3f4-a5b6-7890-cdef-012345678901", "first_name": "Ana", "last_name": "Garcia", "cellphone": "+57300000000" }
    ],
    "internalUsers": [
      { "id": "d4e5f6a7-b8c9-0123-defa-234567890123", "first_name": "Bob", "last_name": "Smith", "cellphone": "+57301000000", "email": "bob.smith@example.com" }
    ],
    "initMessageId": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
    "endMessageId": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
    "createdAt": "2026-05-19T05:03:15.910Z",
    "updatedAt": "2026-05-19T05:03:15.910Z"
  }
}

Atualizações de tarefas

v1 Disparadas quando tarefas são criadas ou seu estado muda, incluindo status, atribuição e lembretes. Os payloads variam conforme o tipo de evento. O campo details descreve o que mudou naquele evento específico.

Tipos de evento
Exemplos de payload

Tipo de evento	Descrição
`task.created`	Uma nova tarefa foi criada
`task.status_changed`	O status da tarefa mudou, por exemplo, de OPEN para CLOSED
`task.assigned`	Um usuário foi atribuído à tarefa
`task.unassigned`	Um usuário deixou de estar atribuído à tarefa
`task.remove_reminder`	Um lembrete da tarefa foi removido
`task.field_updated`	Um campo da tarefa foi atualizado

{
  "eventId": "evt_123456789",
  "eventType": "task.created",
  "entity": "task",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "payload": {
    "taskId": "task_123",
    "actorType": "USER",
    "actorId": "user_123",
    "task": {
      "title": "Sample task",
      "description": "Example task description",
      "type": "TASK",
      "priority": "NORMAL",
      "status": "OPEN",
      "sourceType": "MANUAL",
      "dueDate": "2026-01-20T00:00:00.000Z",
      "recurrenceEnded": false,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    },
    "assignees": [
      { "assigneeId": "user_456", "assigneeType": "USER" }
    ],
    "conversations": [
      {
        "id": "conv_123",
        "status": "ACTIVE",
        "createdAt": "2026-01-14T09:10:00.000Z",
        "updatedAt": "2026-01-14T09:10:00.000Z"
      }
    ]
  }
}

{
  "eventId": "evt_123456790",
  "eventType": "task.assigned",
  "entity": "task",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:31:00.000Z",
  "payload": {
    "taskId": "task_123",
    "actorType": "USER",
    "actorId": "user_123",
    "details": { "assignee": { "assigneeId": "user_456" } }
  }
}

{
  "eventId": "evt_123456791",
  "eventType": "task.unassigned",
  "entity": "task",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:32:00.000Z",
  "payload": {
    "taskId": "task_123",
    "actorType": "USER",
    "actorId": "user_123",
    "details": { "assignee": { "assigneeId": "user_456" } }
  }
}

{
  "eventId": "evt_123456792",
  "eventType": "task.status_changed",
  "entity": "task",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:33:00.000Z",
  "payload": {
    "taskId": "task_123",
    "actorType": "USER",
    "actorId": "user_123",
    "details": {
      "statusChange": { "fromStatus": "OPEN", "toStatus": "CLOSED" }
    }
  }
}

{
  "eventId": "evt_123456793",
  "eventType": "task.status_changed",
  "entity": "task",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:34:00.000Z",
  "payload": {
    "taskId": "task_123",
    "actorType": "USER",
    "actorId": "user_123",
    "task": {
      "title": "Sample task",
      "description": "Example task description",
      "type": "TASK",
      "priority": "NORMAL",
      "status": "OPEN",
      "sourceType": "MANUAL",
      "dueDate": "2026-01-20T00:00:00.000Z",
      "recurrenceEnded": false,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:34:00.000Z"
    },
    "conversations": [
      {
        "id": "conv_123",
        "status": "ACTIVE",
        "createdAt": "2026-01-14T09:10:00.000Z",
        "updatedAt": "2026-01-14T09:10:00.000Z"
      }
    ],
    "details": {
      "statusChange": { "fromStatus": "CLOSED", "toStatus": "OPEN" }
    }
  }
}

{
  "eventId": "evt_123456794",
  "eventType": "task.remove_reminder",
  "entity": "task",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:35:00.000Z",
  "payload": {
    "taskId": "task_456",
    "actorType": "USER",
    "actorId": "user_123",
    "details": { "reminder": { "reminderId": "rem_123" } }
  }
}

{
  "eventId": "evt_123456795",
  "eventType": "task.field_updated",
  "entity": "task",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:36:00.000Z",
  "payload": {
    "taskId": "task_123",
    "actorType": "USER",
    "actorId": "user_123",
    "task": {
      "title": "Sample task",
      "description": "Example updated description",
      "type": "TASK",
      "priority": "NORMAL",
      "status": "OPEN",
      "sourceType": "MANUAL",
      "dueDate": "2026-01-20T00:00:00.000Z",
      "recurrenceEnded": false,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:36:00.000Z"
    },
    "details": {
      "fieldUpdate": { "changedFields": ["description"] }
    }
  }
}

Atualizações de contatos

v1 Disparadas quando registros de contatos são criados, atualizados ou excluídos.

Tipos de evento
Exemplos de payload

Tipo de evento	Descrição
`contact.created`	Um novo contato foi criado
`contact.updated`	Um registro de contato foi atualizado
`contact.deleted`	Um registro de contato foi excluído

Os campos de titularidade dependem de o contato estar vinculado a um CRM externo:

Contatos sincronizados com CRM contêm crmContactId e crmLastSyncedAt; a identidade do contato é gerenciada pelo CRM, não por um usuário interno do Bridge.
Contatos nativos do Bridge, sem vínculo com CRM, contêm internalUserOwnerId: o usuário do Bridge responsável pelo registro.

Esses grupos são mutuamente exclusivos: um contato sincronizado não inclui internalUserOwnerId, e um contato não sincronizado não inclui crmContactId nem crmLastSyncedAt.Cada entrada em openAttributes e closedAttributes inclui um name legível por pessoas junto de customAttributeId. Nos atributos fechados, closedCustomAttributeIds é um array de objetos { id, content }, em que content é o rótulo de exibição da opção selecionada.

{
  "eventId": "evt_contact_001",
  "eventType": "contact.updated",
  "entity": "contact",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "payload": {
    "id": "contact_123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "cellphone": "+1234567890",
    "languageCode": "EN",
    "openAttributes": [
      {
        "customAttributeId": "attr_open_1",
        "name": "Account Number",
        "content": "14"
      }
    ],
    "closedAttributes": [
      {
        "customAttributeId": "attr_closed_1",
        "name": "Preferred Language",
        "closedCustomAttributeIds": [
          { "id": "opt_1", "content": "ENGLISH" }
        ]
      },
      {
        "customAttributeId": "attr_closed_2",
        "name": "Software Tools",
        "closedCustomAttributeIds": [
          { "id": "opt_2", "content": "Go" },
          { "id": "opt_3", "content": "Postgres" }
        ]
      }
    ],
    "crmContactId": "crm_456",
    "crmLastSyncedAt": "2026-01-10T09:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-15T10:30:00.000Z"
  }
}

{
  "eventId": "evt_contact_002",
  "eventType": "contact.updated",
  "entity": "contact",
  "workspaceId": "ws_123",
  "timestamp": "2026-01-15T10:32:00.000Z",
  "payload": {
    "id": "contact_456",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "cellphone": "+1987654321",
    "languageCode": "EN",
    "openAttributes": [
      {
        "customAttributeId": "attr_open_2",
        "name": "Education level",
        "content": "Secondary"
      }
    ],
    "closedAttributes": [
      {
        "customAttributeId": "attr_closed_1",
        "name": "Preferred Language",
        "closedCustomAttributeIds": [
          { "id": "opt_1", "content": "ENGLISH" }
        ]
      },
      {
        "customAttributeId": "attr_closed_3",
        "name": "Gender",
        "closedCustomAttributeIds": [
          { "id": "opt_4", "content": "FEMALE" }
        ]
      }
    ],
    "internalUserOwnerId": "user_789",
    "createdAt": "2026-01-05T15:47:49.000Z",
    "updatedAt": "2026-01-15T10:32:00.000Z"
  }
}

Notificações de chamadas

v1 Disparadas à medida que uma chamada percorre seu ciclo de vida. O Bridge emite no máximo um webhook por fase do ciclo, por chamada. Assim, a integração recebe uma sequência clara de quatro fases — criação, toque, início e término — em vez de todas as transições intermediárias gravadas internamente. A fase atual pode ser determinada pelo estado da chamada e pelo status dos participantes:

Fase	Como identificar
created	O estado é CREATED e nenhum participante ingressou ou está chamando
ringing	Um participante tem status RINGING e ninguém ingressou ainda
started	O estado é STARTED e dois participantes estão JOINED
finished	O estado é FINISHED

Chamadas não atendidas pulam a fase de início: a integração recebe apenas created, ringing e finished. Quando uma chamada termina, o Bridge processa a gravação em um fluxo assíncrono de transcrição por IA. Quando a transcrição fica pronta, a integração recebe um evento adicional call.transcription.created com o texto completo dividido em segmentos por interlocutor e com marcação de tempo. Esse evento chega depois de call.updated (finished), normalmente de alguns segundos a poucos minutos depois, conforme a duração da chamada. A diarização, que identifica os interlocutores, depende da qualidade da fonte de áudio; gravações mono podem produzir um único rótulo de interlocutor para toda a transcrição.

Tipos de evento
Exemplos de payload

Tipo de evento	Descrição
`call.created`	Uma nova chamada foi provisionada
`call.updated`	Uma fase da chamada mudou: toque, início ou término
`call.transcription.created`	A transcrição por IA de uma chamada finalizada está pronta

{
  "eventId": "evt_call_001",
  "eventType": "call.created",
  "entity": "call",
  "workspaceId": "ws_123",
  "timestamp": "2026-05-04T00:48:05.815Z",
  "payload": {
    "callId": "call_abc123",
    "conversationId": "conv_xyz",
    "messageId": "msg_xyz",
    "callType": "ONE_TO_ONE",
    "channelProvider": "WHATSAPP",
    "state": "CREATED",
    "createdAt": "2026-05-04T00:48:05.815Z",
    "updatedAt": "2026-05-04T00:48:05.815Z",
    "participants": {
      "internal": [
        { "userId": "user_internal_1", "name": "Jane Doe", "email": "jane@example.com", "status": "INITIALIZED" }
      ],
      "external": [
        { "userId": "user_external_1", "name": "John Smith", "email": "john@example.com", "status": "INITIALIZED" }
      ]
    }
  }
}

{
  "eventId": "evt_call_002",
  "eventType": "call.updated",
  "entity": "call",
  "workspaceId": "ws_123",
  "timestamp": "2026-05-04T00:48:06.243Z",
  "payload": {
    "callId": "call_abc123",
    "conversationId": "conv_xyz",
    "messageId": "msg_xyz",
    "callType": "ONE_TO_ONE",
    "channelProvider": "WHATSAPP",
    "state": "CREATED",
    "createdAt": "2026-05-04T00:48:05.815Z",
    "updatedAt": "2026-05-04T00:48:06.243Z",
    "participants": {
      "internal": [
        { "userId": "user_internal_1", "name": "Jane Doe", "email": "jane@example.com", "status": "INITIALIZED" }
      ],
      "external": [
        { "userId": "user_external_1", "name": "John Smith", "email": "john@example.com", "status": "RINGING" }
      ]
    }
  }
}

{
  "eventId": "evt_call_003",
  "eventType": "call.updated",
  "entity": "call",
  "workspaceId": "ws_123",
  "timestamp": "2026-05-04T00:48:12.771Z",
  "payload": {
    "callId": "call_abc123",
    "conversationId": "conv_xyz",
    "messageId": "msg_xyz",
    "callType": "ONE_TO_ONE",
    "channelProvider": "WHATSAPP",
    "state": "STARTED",
    "startedAt": "2026-05-04T00:48:12.125Z",
    "createdAt": "2026-05-04T00:48:05.815Z",
    "updatedAt": "2026-05-04T00:48:12.771Z",
    "participants": {
      "internal": [
        { "userId": "user_internal_1", "name": "Jane Doe", "email": "jane@example.com", "status": "JOINED", "joinedAt": "2026-05-04T00:48:12.125Z" }
      ],
      "external": [
        { "userId": "user_external_1", "name": "John Smith", "email": "john@example.com", "status": "JOINED", "joinedAt": "2026-05-04T00:48:12.124Z" }
      ]
    }
  }
}

{
  "eventId": "evt_call_004",
  "eventType": "call.updated",
  "entity": "call",
  "workspaceId": "ws_123",
  "timestamp": "2026-05-04T00:48:20.113Z",
  "payload": {
    "callId": "call_abc123",
    "conversationId": "conv_xyz",
    "messageId": "msg_xyz",
    "callType": "ONE_TO_ONE",
    "channelProvider": "WHATSAPP",
    "state": "FINISHED",
    "startedAt": "2026-05-04T00:48:12.125Z",
    "finishedAt": "2026-05-04T00:48:19.389Z",
    "createdAt": "2026-05-04T00:48:05.815Z",
    "updatedAt": "2026-05-04T00:48:20.113Z",
    "participants": {
      "internal": [
        { "userId": "user_internal_1", "name": "Jane Doe", "email": "jane@example.com", "status": "LEFT", "joinedAt": "2026-05-04T00:48:12.125Z", "leftAt": "2026-05-04T00:48:19.388Z" }
      ],
      "external": [
        { "userId": "user_external_1", "name": "John Smith", "email": "john@example.com", "status": "LEFT", "joinedAt": "2026-05-04T00:48:12.124Z", "leftAt": "2026-05-04T00:48:19.387Z" }
      ]
    }
  }
}

{
  "eventId": "evt_call_005",
  "eventType": "call.transcription.created",
  "entity": "call",
  "workspaceId": "ws_123",
  "timestamp": "2026-05-04T00:50:14.231Z",
  "payload": {
    "callId": "call_abc123",
    "transcriptionId": "txn_xyz789",
    "conversationId": "conv_xyz",
    "duration": "27",
    "startedAt": "2026-05-04T00:48:12.125Z",
    "finishedAt": "2026-05-04T00:48:19.389Z",
    "transcript": [
      { "speaker": "0", "text": "Hi, how can I help you today?", "start": 1.44, "end": 5.2 },
      { "speaker": "1", "text": "I have a question about your product.", "start": 5.5, "end": 12.3 }
    ]
  }
}

Cada segmento da transcrição contém o rótulo speaker da diarização, normalmente "0", "1" etc., o text e os deslocamentos start/end em segundos desde o início da chamada.

Notificações de reuniões

v1 Disparadas quando uma reunião chega ao estado CREATED. Cancelamentos de reuniões são informados pela notificação de e-mail correspondente.

Tipos de evento
Exemplo de payload

Tipo de evento	Descrição
`meeting.updated`	Uma reunião chegou ao estado `CREATED`

{
  "eventId": "evt_meeting_001",
  "eventType": "meeting.updated",
  "entity": "meeting",
  "workspaceId": "ws_123",
  "timestamp": "2026-05-04T00:46:40.954Z",
  "payload": {
    "meetingId": "meeting_abc123",
    "conversationId": "conv_xyz",
    "messageId": "msg_xyz",
    "subject": "Meeting with John Smith",
    "providerType": "TEAMS",
    "status": "CREATED",
    "organizerInternalUserId": "user_internal_1",
    "internalParticipants": ["user_internal_1"],
    "externalParticipants": ["user_external_1"],
    "startDateTime": "2026-05-04T01:00:00.000Z",
    "endDateTime": "2026-05-04T01:15:00.000Z",
    "createdAt": "2026-05-04T00:46:29.944Z",
    "updatedAt": "2026-05-04T00:46:40.954Z",
    "provider": {
      "joinUrl": "https://teams.microsoft.com/l/meetup-join/...",
      "calendarEventId": "AAMkADhlMWVlMWJhLWUyZTMtNDllOC...",
      "chatId": "MWM1Zjg4MmUtZjk0Mi00YjJkLTgyNTItNmRiODNiZmM1NWEw",
      "providerMeetingId": "MSowODJkZmFjYy1iNDZmLTRiNDItOGYzOS0xMzI0NDcyMzUwMWUq..."
    }
  }
}

Notificações de e-mail

v1 Disparadas depois que um e-mail é processado e o resumo por IA está disponível. O campo sentFromBridge indica a direção: true para e-mails enviados pelo workspace, false para e-mails recebidos.

Tipos de evento
Exemplo de payload

Tipo de evento	Descrição
`email.updated`	Um e-mail chegou ao estado resumido

{
  "eventId": "evt_email_001",
  "eventType": "email.updated",
  "entity": "email",
  "workspaceId": "ws_123",
  "timestamp": "2026-05-04T00:45:31.261Z",
  "payload": {
    "emailId": "email_abc123",
    "conversationId": "conv_xyz",
    "threadId": "AAQkADhlMWVlMWJhLWUyZTMtNDllOC05MDg2LWMzNjFkMTI5MjM4MA...",
    "providerType": "OUTLOOK",
    "status": "PROCESSED",
    "subject": "Project update",
    "sender": "jane@example.com",
    "recipients": [
      { "recipientEmail": "john@example.com" }
    ],
    "summary": "Jane confirms the project is on track and shares next steps.",
    "importance": "NORMAL",
    "sentFromBridge": true,
    "hasAttachments": false,
    "sentAt": "2026-05-04T00:45:09.000Z",
    "createdAt": "2026-05-04T00:45:09.000Z",
    "updatedAt": "2026-05-04T00:45:31.261Z"
  }
}

Observações

O Bridge pode acrescentar novas categorias de eventos no futuro.
Sempre verifique o campo de tipo de evento para escolher qual tratador executar.
Configure e dê suporte à versão selecionada para cada assinatura de evento. O envelope comum não declara um campo universal version; não o exija nem o invente. Veja recebimento de eventos para tratar duplicatas e ordenação.