Webhooks de Reglas | Plazbot Docs

Las Reglas de Plazbot (Automatizaciones → Reglas) permiten disparar un webhook saliente hacia tu endpoint cuando ocurre un evento en el workspace. Es la forma recomendada de sincronizar Plazbot con sistemas externos (CRM, Meta Conversions API, ERP) sin hacer polling.

Cómo se configura

En el panel: Automatizaciones → Reglas → Nueva regla.
Elige el disparador (por ejemplo "Se asigne una fase").
Agrega la acción "Enviar Webhook" con la URL de tu endpoint, el método (POST o GET) y headers personalizados si los necesitas (por ejemplo un token de autenticación propio).

El webhook se envía de forma asincrona (no bloquea el flujo del contacto) con un timeout de 10 segundos.

Disparadores disponibles

Disparador	Se dispara cuando...
`contacto_nuevo`	Se crea un contacto nuevo.
`contacto_nuevo_facebookads`	Un contacto nuevo entra por un anuncio de Facebook (Click-to-WhatsApp).
`contacto_nuevo_instagramads`	Un contacto nuevo entra por un anuncio de Instagram.
`meta_lead_nuevo`	Llega un lead de Meta Lead Ads.
`contacto_existente`	Un contacto ya registrado envía un mensaje.
`contacto_resuelto` / `contacto_reabierto`	La conversación se marca como resuelta o se reabre.
`asignar_fase`	El contacto cambia de fase (operadores IS / ISNOT / ANY).
`asignar_etiqueta` / `asignar_segmentacion` / `asignar_agente`	Se asigna etiqueta, segmentación o agente.
`tarea_creada`	Se crea una tarea.
`oportunidad_creada`	Se crea una oportunidad.
`oportunidad_ganada` / `oportunidad_perdida`	Una oportunidad se marca como ganada o perdida (condiciones por monto y pipeline).

Payload: eventos de contacto

Para los disparadores de contacto (incluido asignar_fase), el POST a tu endpoint lleva:

json

01{
02  "trigger": "AsignarFase",
03  "timestamp": "2026-09-23T15:04:05.000Z",
04  "workspaceId": "wok_xxxxxxxx",
05  "contact": {
06    "id": "ctc_xxxxxxxx",
07    "name": "Juan",
08    "lastname": "Perez",
09    "email": "juan@ejemplo.com",
10    "phoneNumber": "51987654321",
11    "internalWhatsappNumber": "51987654321",
12    "isoCountryCode": "PE",
13    "phoneCountryDialCode": "+51",
14    "platformId": 2,
15    "assignedAgentId": "...",
16    "assignedAgentName": "...",
17    "stageId": "stg_xxxxxxxx",
18    "stageName": "Calificado",
19    "segmentationId": "...",
20    "tags": [{ "id": "...", "name": "..." }],
21    "isSolved": false,
22    "variables": [{ "code": "ctc_1234567", "val": "..." }],
23    "customFields": [],
24    "adsReferralData": {
25      "type": "ad",
26      "adId": "1234567890",
27      "title": "Titulo del anuncio",
28      "url": "https://fb.me/...",
29      "ctwaClid": "ARAe..."
30    },
31    "creationDate": "...",
32    "firstMessage": "Hola, vengo de la promo X",
33    "firstMessageDate": "...",
34    "lastMessage": "...",
35    "lastMessageDate": "...",
36    "events": []
37  }
38}

Campos útiles para integraciones:

internalWhatsappNumber: la llave estable del contacto — código de país + número, solo digitos, sin +. Para formato E.164 anteponer +.
stageId / stageName: la fase nueva del contacto (útil para senales de calificacion a Meta Conversions API).
adsReferralData: la atribución del anuncio por el que entro el contacto (adId, ctwaClid, title, url). Viaja en cada webhook, así que puedes cerrar el bucle de conversion sin llamadas extra.
variables: los campos personalizados del contacto como { code, val }.
firstMessage: el primer mensaje que envio el contacto. En un enlace click-to-chat (wa.me/...?text=...) es el texto precargado del enlace, así que sirve para atribuir la campana u origen de contactos que no vienen de anuncios pagos.

Payload: oportunidades

Para oportunidad_creada, oportunidad_ganada y oportunidad_perdida:

json

01{
02  "trigger": "OportunidadGanada",
03  "timestamp": "2026-09-23T15:04:05.000Z",
04  "workspaceId": "wok_xxxxxxxx",
05  "opportunity": {
06    "id": "...",
07    "opportCode": "...",
08    "name": "...",
09    "amount": 1500,
10    "finalAmount": 1400,
11    "contactId": "ctc_xxxxxxxx",
12    "stageId": "...",
13    "pipelineId": "...",
14    "winLossStatus": 1,
15    "winLossDate": "...",
16    "currencyCode": "USD",
17    "creationDate": "..."
18  }
19}

winLossStatus: 1 = ganada, 2 = perdida.

Payload: tareas

Para tarea_creada:

json

01{
02  "trigger": "TareaCreada",
03  "timestamp": "2026-09-23T15:04:05.000Z",
04  "workspaceId": "wok_xxxxxxxx",
05  "task": {
06    "id": "...",
07    "name": "...",
08    "description": "...",
09    "creationDate": "...",
10    "expirationDate": "...",
11    "statusId": "...",
12    "asignedUsers": [],
13    "dealId": "..."
14  }
15}

Cobertura del disparador asignar_fase

El webhook de cambio de fase se dispara cuando la fase cambia desde:

El panel de Plazbot (arrastrar en Kanban, editar el contacto).
La API (PUT /api/contact, POST /api/contact/upsert).
Botones de mensajes con acciones de fase.
Nodos de automatización que asignan fase.

Todavía no se dispara cuando la fase la cambia una acción action.stage de un agente IA ni en movimientos masivos de contactos (bulk). Esta cobertura está en el roadmap.

Recomendaciones

Responde 200 rápido (menos de 10 segundos) y procesa en segundo plano; Plazbot no reintenta entregas fallidas.
Valida la autenticidad con un header personalizado propio (configurable en la acción del webhook).
El webhook lleva el estado del contacto al momento del evento; si necesitas el estado más reciente, consulta GET /api/contact/{id}.