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.

Como se configura

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

El webhook se envia 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 envia un mensaje.
`contacto_resuelto` / `contacto_reabierto`	La conversacion 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, segmentacion 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 utiles para integraciones:

internalWhatsappNumber: la llave estable del contacto — codigo de pais + numero, solo digitos, sin +. Para formato E.164 anteponer +.
stageId / stageName: la fase nueva del contacto (util para senales de calificacion a Meta Conversions API).
adsReferralData: la atribucion del anuncio por el que entro el contacto (adId, ctwaClid, title, url). Viaja en cada webhook, asi 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, asi 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 automatizacion que asignan fase.

Todavia no se dispara cuando la fase la cambia una accion action.stage de un agente IA ni en movimientos masivos de contactos (bulk). Esta cobertura esta en el roadmap.

Recomendaciones

Responde 200 rapido (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 accion del webhook).
El webhook lleva el estado del contacto al momento del evento; si necesitas el estado mas reciente, consulta GET /api/contact/{id}.