Eventos de webhook - Bridge REST Integrations API & Webhooks

Los webhooks de Bridge entregan cuerpos de eventos estructurados en JSON cuando ocurren acciones específicas en tu espacio de trabajo. Cada evento sigue un esquema consistente para facilitar su interpretación y validación.

Estructura común de los eventos

El ejemplo siguiente ilustra el sobre común: "string" representa un tipo, no un valor de evento para enviar. Lee los ejemplos de cada familia más abajo. No asumas que eventId sea globalmente único entre familias de notificaciones.

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

Notificaciones de resúmenes de conversación

v1 Se activan una vez al día por conversación cuando Bridge AI genera el resumen diario. El resumen recoge los puntos principales del intercambio y los participantes internos y externos involucrados.

Tipos de eventos
Ejemplo de cuerpo

Tipo de evento	Descripción
`conversation_summary.created`	Se generó el resumen diario de una conversación

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

Actualizaciones de tareas

v1 Se activan cuando se crean tareas o cambian su estado, asignación o recordatorios. Los cuerpos varían según el tipo de evento. El campo details explica qué cambió en ese evento específico.

Tipos de eventos
Ejemplos de cuerpos

Tipo de evento	Descripción
`task.created`	Se creó una tarea
`task.status_changed`	Cambió el estado de la tarea, por ejemplo, de OPEN a CLOSED
`task.assigned`	Se asignó un usuario a la tarea
`task.unassigned`	Se quitó la asignación de un usuario a la tarea
`task.remove_reminder`	Se eliminó un recordatorio de la tarea
`task.field_updated`	Se actualizó un campo de la tarea

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

Actualizaciones de contactos

v1 Se activan cuando se crean, actualizan o eliminan registros de contactos.

Tipos de eventos
Ejemplos de cuerpos

Tipo de evento	Descripción
`contact.created`	Se creó un contacto
`contact.updated`	Se actualizó un registro de contacto
`contact.deleted`	Se eliminó un contacto

Los campos de propiedad dependen de si el contacto está vinculado a un CRM externo:

Los contactos sincronizados con un CRM incluyen crmContactId y crmLastSyncedAt: la identidad del contacto la controla el CRM, no un usuario interno de Bridge.
Los contactos nativos de Bridge, sin vínculo a un CRM, incluyen en cambio internalUserOwnerId, que identifica al usuario de Bridge propietario del registro.

Estos grupos son mutuamente excluyentes: un contacto sincronizado no incluye internalUserOwnerId, y uno no sincronizado no incluye crmContactId ni crmLastSyncedAt.Cada entrada de openAttributes y closedAttributes incluye un name legible junto a customAttributeId. Para atributos cerrados, closedCustomAttributeIds es un array de objetos { id, content }, donde content es la etiqueta visible de la opción elegida.

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

Notificaciones de llamadas

v1 Se activan cuando una llamada avanza por su ciclo de vida. Bridge emite como máximo un webhook por fase y llamada. Tu integración recibe una secuencia clara de cuatro fases —creada, sonando, iniciada y finalizada— en lugar de cada transición intermedia que Bridge registra internamente. La fase actual se puede deducir del estado de la llamada y de los estados de sus participantes:

Fase	Cómo detectarla
created	El estado es CREATED y ningún participante se ha unido ni está sonando
ringing	Un participante tiene estado RINGING y nadie se ha unido todavía
started	El estado es STARTED y dos participantes están JOINED
finished	El estado es FINISHED

Las llamadas perdidas, en las que nadie responde, omiten la fase started: la integración recibe únicamente created, ringing y finished. Cuando termina la llamada, Bridge procesa la grabación mediante un flujo asíncrono de transcripción con IA. Cuando está lista, la integración recibe un evento adicional call.transcription.created con la transcripción completa dividida en segmentos por hablante y con marcas de tiempo. Este evento llega después de call.updated (finished), normalmente entre varios segundos y unos minutos más tarde según la duración de la llamada. La diarización —identificación de distintos hablantes— depende de la calidad del audio de origen: una grabación mono puede producir una sola etiqueta de hablante para toda la transcripción.

Tipos de eventos
Ejemplos de cuerpos

Tipo de evento	Descripción
`call.created`	Se aprovisionó una llamada
`call.updated`	Cambió una fase del ciclo de vida de la llamada: sonando, iniciada o finalizada
`call.transcription.created`	Está lista la transcripción de IA de una llamada finalizada

{
  "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 de transcripción incluye la etiqueta de hablante speaker, normalmente "0", "1", etc., el text y los desplazamientos start/end en segundos desde el inicio de la llamada.

Notificaciones de reuniones

v1 Se activan cuando una reunión alcanza el estado CREATED. Las cancelaciones se comunican mediante la notificación de correo correspondiente.

Tipos de eventos
Ejemplo de cuerpo

Tipo de evento	Descripción
`meeting.updated`	Una reunión alcanzó el 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..."
    }
  }
}

Notificaciones de correo electrónico

v1 Se activan cuando se ha procesado un correo y está disponible su resumen de IA. El campo sentFromBridge indica la dirección: true para correos salientes enviados desde el espacio de trabajo y false para correos entrantes recibidos.

Tipos de eventos
Ejemplo de cuerpo

Tipo de evento	Descripción
`email.updated`	Un correo alcanzó el estado con resumen disponible

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

Notas

Bridge puede agregar nuevas categorías de eventos en el futuro.
Revisa siempre el campo de tipo de evento para determinar qué manejador ejecutar.
Configura y admite la versión seleccionada para cada suscripción. El sobre común no declara un campo version universal: no lo exijas ni lo inventes. Consulta Recepción de eventos para los duplicados y el orden.