# Webhooks: lleva cada envío a tu sistema

> En Webhooks, crea un webhook con método, URL, encabezados y cuerpo JSON con variables como {{ lead.name() }}. Pruébalo con un contacto ficticio, adjunta hasta 3 webhooks a una campaña de email (o usa solo webhooks) y revisa cada entrega en los logs. Si el destino falla, la BIP intenta hasta 6 veces, cada 60 segundos.

Fonte: https://wiki.bip.marketing/es-es/webhooks · Atualizado: 2026-10-08

<UseCaseMeta effort="nocode" channel="webhook" plan="free" />

Cada vez que una campaña llega a un contacto, la BIP puede avisarle a otro sistema: crear el contacto en el CRM, mandarle un mensaje al equipo, alimentar una hoja de cálculo. Armas la solicitud una sola vez en el panel, con los datos del contacto en el lugar correcto, y la BIP hace el resto en cada envío.

<Checklist items="Una cuenta en la BIP (sirve el plan gratuito)|La dirección (URL) que va a recibir los datos y el token de acceso, si el destino lo pide|Una campaña de email, recurrente, única o por API, para adjuntarle el webhook" />

## Lo que vas a lograr

- Cada contacto de la campaña llega a tu CRM o herramienta, con el nombre, email, teléfono, ciudad, campos y KPIs que elijas.
- Todo en el panel, sin código: método, URL, encabezados y cuerpo, con sugerencias de variables y vista previa.
- Entregas que se recuperan solas: si el destino falla, la BIP vuelve a intentarlo.
- Logs con la solicitud y la respuesta de cada entrega, y métricas por webhook.
- Campañas solo con webhooks, para sincronizar sistemas sin enviar emails.

## Cómo funciona

<Steps items="Crea el webhook con URL, encabezados y cuerpo|Pruébalo con un contacto ficticio y revisa el log|Adjúntalo a una campaña: cada contacto procesado dispara el webhook" />

Un webhook es una solicitud HTTP que la BIP le hace a tu sistema. Tú defines el método, la URL, los encabezados y el cuerpo en JSON. En el cuerpo, variables como `{{ lead.name() }}` se convierten en los datos de cada contacto en el momento del envío.

El webhook se ejecuta cuando está adjunto a una campaña. Por cada contacto que procesa la campaña, la BIP arma el cuerpo con los datos de esa persona y lo envía. Funciona en campañas **Único**, **Recurrente** y **Disparo por API**. Quien se dio de baja de todas las comunicaciones no dispara el webhook.

La entrega es exitosa cuando tu sistema responde con un código 2xx (200, 201, 204…). Cualquier otra respuesta, o la falta de respuesta, genera un nuevo intento 60 segundos después. Son hasta 6 intentos en total: el primero y 5 más.

## Paso a paso

### 1. Crea el webhook

1. En el menú, abre **Webhooks** y haz clic en **Nuevo webhook**. La BIP crea un webhook **[sin título]** y abre su página.
2. En **Configuración de webhook**, elige el método. Para enviar los datos del contacto, usa **POST** (o **PUT**, si el destino lo pide).
3. Pega la URL que va a recibir los datos en lugar de `http://your-webhook-endpoint.com`.
4. Haz clic en **Guardar**.

<Shot src="/img/webhooks/1-es-es.png" alt="Página del webhook con método y URL en Configuración de webhook" url="dash.bip.marketing/…/webhooks/…" />

### 2. Arma los encabezados y el cuerpo

1. Abre **Encabezados** y escribe un objeto JSON. Incluye siempre `"Content-Type": "application/json"`: la BIP envía el cuerpo como JSON y la mayoría de los sistemas revisa ese encabezado. Si el destino pide un token, agrégalo también, por ejemplo `"Authorization": "Bearer TU_TOKEN"`.
2. En **Plantilla del cuerpo**, escribe el JSON que espera el destino. Dentro de un valor entre comillas, escribe `{{` y elige la variable en la lista de sugerencias. El ícono de ayuda junto a **Plantilla del cuerpo** muestra todas las variables.
3. Revisa la **Vista previa** a la derecha: muestra el cuerpo listo, con los datos de un contacto ficticio, y se actualiza en cuanto dejas de escribir.
4. Haz clic en **Guardar**.

El cuerpo tiene que ser un JSON válido para guardarse. Por eso, cada variable va entre comillas y llega al destino como texto: `"vip": "{{ lead.hasTag('vip') }}"` se convierte en `"vip": "true"`.

Para un valor de respaldo cuando el dato está vacío, usa `||`: `"saudacao": "Hola, {{ lead.firstName() || 'cliente' }}"`.

<Shot src="/img/webhooks/2-es-es.png" alt="Encabezados, plantilla del cuerpo con variables y vista previa del webhook" url="dash.bip.marketing/…/webhooks/…" />

<Callout type="tip">
Para campos personalizados, KPIs y etiquetas, elige siempre desde la lista de sugerencias. La lista muestra el nombre que conoces y guarda el identificador interno que la BIP usa para encontrar el dato.
</Callout>

### 3. Ponle nombre y organízalo

1. En la parte superior de la página, haz clic en **Ajustes**.
2. Completa el **Nombre** (es lo que aparece al adjuntarlo a campañas), elige un ícono y, si quieres, una **Descripción**.
3. En **Grupo**, elige un grupo para organizar la lista. Los grupos de webhooks se crean en **Ajustes** → **Grupos**.
4. En **Estado**, deja **Activo** encendido.
5. Haz clic en **Guardar**.

<Shot src="/img/webhooks/3-es-es.png" alt="Ajustes del webhook con nombre, ícono, descripción, grupo y estado" url="dash.bip.marketing/…/webhooks/…" />

### 4. Pruébalo con un contacto ficticio

1. Con todo guardado, haz clic en **Probar webhook**. El botón está disponible cuando no hay cambios sin guardar.
2. La BIP envía una solicitud real a tu URL, con un contacto ficticio (nombre, email, teléfono y ciudades inventados; campos personalizados vacíos), y abre **Estadísticas del Webhook**.
3. En **Logs de Entrega**, haz clic en **Ver** en la fila de la prueba. **Solicitud** muestra lo que envió la BIP; **Respuesta** muestra el código y el cuerpo que devolvió tu sistema.

La prueba llega de verdad a tu sistema. Si el destino es el CRM en producción, borra el registro de prueba después, o apunta primero a un entorno de pruebas.

<Shot src="/img/webhooks/4-es-es.png" alt="Estadísticas del webhook con el log de entrega de la prueba" url="dash.bip.marketing/…/webhooks/stats/…" />

### 5. Adjúntalo a una campaña

1. En **Campañas**, abre una campaña o haz clic en **Nueva campaña**, con el **Canal** **Email**.
2. En la sección **Webhooks**, selecciona hasta 3 webhooks. Cada contacto procesado los dispara todos.
3. Para una campaña **solo con webhooks**, no elijas **Plantilla de email** y selecciona al menos un webhook. No sale ningún email: cada contacto solo dispara los webhooks.
4. Elige el **Tipo de Programación** (**Único**, **Recurrente** o **Disparo por API**), guarda y activa como cualquier campaña.

<Shot src="/img/webhooks/5-es-es.png" alt="Sección Webhooks de una campaña de email con webhooks seleccionados" url="dash.bip.marketing/…/campaigns/…" />

<PlanOnly plan="full">
En **Flujos**, el paso **Enviar webhook** usa los mismos webhooks: el contacto dispara el webhook cuando llega a ese punto del flujo.
</PlanOnly>

## Referencia

### Configuración del webhook

| Opción               | Cómo funciona                                                            |
| -------------------- | ------------------------------------------------------------------------ |
| Método               | GET, POST, PUT o DELETE. Para enviar datos en el cuerpo, usa POST o PUT. |
| URL                  | Dirección de destino. Fija: no acepta variables.                         |
| Encabezados          | Objeto JSON, como `{"Content-Type": "application/json"}`. Fijos.         |
| Plantilla del cuerpo | JSON válido, con las variables del contacto entre comillas.              |
| Nombre, ícono        | Cómo aparece el webhook en la lista y en las campañas.                   |
| Descripción          | Texto libre, para el equipo.                                             |
| Grupo                | Organiza la lista de **Webhooks**.                                       |
| Estado               | **Activo** o inactivo.                                                   |

### Entrega y reintentos

| Regla                 | Valor                                                       |
| --------------------- | ----------------------------------------------------------- |
| Éxito                 | Respuesta con código 2xx                                    |
| Reintento             | Cualquier otro código, o sin respuesta                      |
| Intervalo             | 60 segundos                                                 |
| Intentos en total     | 6 (el primero y 5 más)                                      |
| Después del 6.º fallo | La campaña registra un error de webhook para ese contacto   |
| Webhooks por campaña  | Hasta 3, en campañas del canal Email, con o sin email       |

### Variables del contacto

Úsalas dentro de un valor entre comillas. El resultado llega como texto.

| Variable                                | Qué trae                                               |
| --------------------------------------- | ------------------------------------------------------ |
| `{{ lead.name() }}`                     | Nombre completo                                        |
| `{{ lead.firstName() }}`                | Primer nombre                                          |
| `{{ lead.middleName() }}`               | Segundos nombres                                       |
| `{{ lead.lastName() }}`                 | Apellido                                               |
| `{{ lead.email() }}`                    | Email                                                  |
| `{{ lead.id() }}`                       | ID del contacto en la BIP                              |
| `{{ lead.namespace() }}`                | Namespace de la cuenta                                 |
| `{{ lead.createdAt() }}`                | Fecha de creación, en formato ISO 8601                 |
| `{{ lead.createdAt('YYYY-MM-DD') }}`    | Fecha de creación con formato                          |
| `{{ lead.updatedAt() }}`                | Última actualización, en formato ISO 8601              |
| `{{ lead.updatedAt('YYYY-MM-DD') }}`    | Última actualización con formato                       |
| `{{ lead.metadata('[METADATA_KEY]') }}` | Un metadato: cambia `[METADATA_KEY]` por la clave      |
| `{{ lead.sourceType('first') }}`        | Tipo de la primera fuente (`api`, `internal`, `page`…) |
| `{{ lead.sourceType('last') }}`         | Tipo de la última fuente                               |

### Variables de teléfono

| Variable                                           | Ejemplo                              |
| -------------------------------------------------- | ------------------------------------ |
| `{{ lead.phone('e164') }}`                         | `+5511912345678`                     |
| `{{ lead.phone('international') }}`                | `+55 11 91234-5678`                  |
| `{{ lead.phone('national') }}`                     | `(11) 91234-5678`                    |
| `{{ lead.phone('nationalNumber') }}`               | `11912345678`                        |
| `{{ lead.phone('countryCallingCode') }}`           | `55`                                 |
| `{{ lead.phone('countryCode') }}`                  | `BR`                                 |
| `{{ lead.phone('numberType') }}`                   | `MOBILE`                             |
| `{{ lead.phone('uri') }}`                          | `tel:+5511912345678`                 |
| `{{ lead.maskedPhone('e164', '(999) 999-9999') }}` | Teléfono con la máscara que definas  |

En la máscara, cada `9` es un dígito, que se completa de izquierda a derecha. Para el formato brasileño, usa `{{ lead.maskedPhone('national', '(99) 99999-9999') }}`.

### Variables de ubicación

| Variable                                   | Qué trae                                 |
| ------------------------------------------ | ---------------------------------------- |
| `{{ lead.location('last', 'city') }}`      | Ciudad de la última ubicación            |
| `{{ lead.location('last', 'region') }}`    | Estado o región de la última ubicación   |
| `{{ lead.location('last', 'country') }}`   | País de la última ubicación              |
| `{{ lead.location('last', 'timezone') }}`  | Zona horaria de la última ubicación      |
| `{{ lead.location('last', 'latitude') }}`  | Latitud del centro de la ciudad          |
| `{{ lead.location('last', 'longitude') }}` | Longitud del centro de la ciudad         |

Cambia `last` por `first` para la primera ubicación. La ubicación siempre es la de la ciudad.

### Variables de baja (opt-out)

| Variable                                         | Qué trae                                                        |
| ------------------------------------------------ | --------------------------------------------------------------- |
| `{{ lead.unsubscribed() }}`                      | `true` si la persona se dio de baja de todas las comunicaciones |
| `{{ lead.unsubscribedFromChannel('email') }}`    | `true` si se dio de baja del email                              |
| `{{ lead.unsubscribedFromChannel('whatsapp') }}` | `true` si se dio de baja de WhatsApp                            |

### Variables de tu cuenta

El editor crea estas variables a partir de tus campos personalizados, KPIs y etiquetas. En la lista de sugerencias, aparecen con el nombre que les diste.

| Variable                                                                    | Para                                                                                  |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `{{ lead.field('Nombre del campo') }}`                                      | Campos Cadena, Número, Booleano y Fecha                                               |
| `{{ lead.dateField('Nombre del campo', 'YYYY-MM-DD') }}`                    | Campo Fecha, en el formato que elijas                                                 |
| `{{ lead.ageField('Nombre del campo') }}`                                   | Edad en años, a partir de un campo Fecha                                              |
| `{{ lead.locationField('Nombre del campo', 'city') }}`                      | Campo Ubicación (también `region`, `country`, `timezone`, `latitude`, `longitude`)    |
| `{{ lead.phoneField('Nombre del campo', 'e164') }}`                         | Campo Teléfono (también los formatos de la tabla de teléfono)                         |
| `{{ lead.maskedPhoneField('Nombre del campo', 'e164', '(999) 999-9999') }}` | Campo Teléfono con máscara                                                            |
| `{{ lead.maskedNumberField('Nombre del campo', '999 999 999 99') }}`        | Campo Número con máscara                                                              |
| `{{ lead.kpi('Nombre del KPI') }}`                                          | Valor de un KPI                                                                       |
| `{{ lead.hasTag('Nombre de la etiqueta') }}`                                | `true` si el contacto tiene la etiqueta                                               |

## Listo para copiar

### Enviar cada contacto a un CRM

Agência Pulso envía a su CRM a cada persona que recibe la campaña de bienvenida. Ajusta los nombres de las claves a lo que espera tu CRM.

<Copy label="Encabezados" code>
{
  "Content-Type": "application/json",
  "Authorization": "Bearer TU_TOKEN_DEL_CRM"
}
</Copy>

<Copy label="Plantilla del cuerpo" code>
{
  "nome": "{{ lead.name() }}",
  "email": "{{ lead.email() }}",
  "telefone": "{{ lead.phone('e164') }}",
  "cidade": "{{ lead.location('last', 'city') }}",
  "estado": "{{ lead.location('last', 'region') }}",
  "origem": "bip",
  "id_bip": "{{ lead.id() }}",
  "criado_em": "{{ lead.createdAt('YYYY-MM-DD') }}"
}
</Copy>

| Configuración | Valor                                              |
| ------------- | -------------------------------------------------- |
| Método        | POST                                               |
| URL           | La dirección de creación de contactos de tu CRM    |
| Campaña       | Canal **Email**, con o sin **Plantilla de email**  |
| Webhooks      | Este webhook (hasta 3 por campaña)                 |

Para enviar al CRM a cada persona en el momento del registro, sin email: crea una campaña solo con este webhook, con **Disparo por API** en modo **Inmediato**, y dispárala por la [API](/es-es/api) cuando alguien se registre.

### Avisar al equipo

Muchas herramientas de chat y de automatización reciben mensajes por un webhook entrante, con el texto en el campo `text`. Imobiliária Marés avisa a sus agentes por cada persona que entra en la campaña de lanzamiento.

<Copy label="Encabezados" code>
{
  "Content-Type": "application/json"
}
</Copy>

<Copy label="Plantilla del cuerpo" code>
{
  "text": "Nuevo interesado: {{ lead.name() }} | {{ lead.email() || 'sin email' }} | {{ lead.phone('international') || 'sin teléfono' }} | {{ lead.location('last', 'city') || 'ciudad no informada' }}"
}
</Copy>

Revisa en la herramienta de destino el nombre del campo de texto que espera y cambia `text` si hace falta.

## Cómo medir

- **Estadísticas del Webhook**: en la lista de **Webhooks**, abre el webhook y haz clic en **Ver Estadísticas**. Ves **Total de Solicitudes**, **Exitoso**, **Fallido**, **Tiempo Promedio de Respuesta**, **Tasa de Éxito**, **Tasa de Reintento**, **Tasa de Error**, **Códigos de Estado** y el **Desglose de Entregas**. Los números se actualizan **En vivo**.
- **Logs de Entrega**: filtra por **Desde la fecha**, **Hasta la fecha** y **Límite**. Cada fila trae **Fecha**, **Estado**, **URL**, **Método** e **Intentos**; en **Ver**, revisas la **Solicitud** y la **Respuesta** completas.
- **En la campaña**: en **Ver Estadísticas**, **Entrega de Webhook** y **Errores de Webhook** muestran el total de la campaña, e **Interacciones del destinatario** muestra el webhook de cada contacto.
- Una **Tasa de Reintento** alta indica que el destino está lento o inestable. Abre la **Respuesta** en los logs para ver el motivo.

## Preguntas frecuentes

### ¿Qué cuenta como entrega exitosa?

Una respuesta con código 2xx. Cualquier otro código, o la falta de respuesta, genera un nuevo intento 60 segundos después, hasta 6 intentos en total. Después del sexto fallo, la campaña registra el error de ese contacto.

### ¿El webhook cuenta como envío?

En una campaña de email con webhooks, cuenta el envío de ese contacto, una sola vez: los webhooks no suman. En una campaña solo con webhooks, cada contacto procesado cuenta como un envío, como si fuera un email. **Probar webhook** no cuenta.

### ¿Puedo usar variables en la URL o en los encabezados?

No. La URL y los encabezados son fijos. Las variables del contacto funcionan en la **Plantilla del cuerpo**.

### ¿La prueba llega a mi sistema?

Sí. **Probar webhook** hace una solicitud real, con un contacto ficticio. Usa un entorno de pruebas o borra el registro después.

## Ver también

- [Campañas: únicas, recurrentes y por API](/es-es/campanas)
- [API de la BIP: claves, contactos, eventos y disparos](/es-es/api)
- [Script del sitio: páginas vistas y clics vinculados al contacto](/es-es/script-del-sitio)
- [Cumplimiento: portal de preferencias, bajas y temas](/es-es/cumplimiento)
- [Referencia completa de la API](https://bipmarketing.readme.io)