1. ¿Qué necesitas para configurar un Webhook?
Para recibir información de Wechatia necesitarás crear un endpoint en tuSoftware.
Por ejemplo:
https://api.tuSoftware.com/webhooks/wechatia
Esta será la dirección a la que Wechatia enviará los eventos.
Necesitarás:
- URL del Webhook.
Location ID.- Endpoint preparado para recibir solicitudes
POST.
- Sistema para procesar los eventos recibidos.
- Identificador del contacto (
Contact ID) para relacionar la información.
2. Crear el endpoint en tuSoftware
El primer paso es crear un endpoint en tuSoftware que pueda recibir solicitudes HTTP.
Por ejemplo:
https://api.tuSoftware.com/webhooks/wechatia
Este endpoint debe aceptar solicitudes:
POST
La estructura será:
Wechatia
│
│ POST
▼
https://api.tuSoftware.com/webhooks/wechatia
La URL utilizada en este ejemplo es únicamente un ejemplo. Debes reemplazarla por la URL real de tuSoftware.
3. Preparar tuSoftware para recibir información
Cuando Wechatia envíe un Webhook, tuSoftware recibirá una solicitud HTTP.
Tu servidor debe estar preparado para:
- Recibir la solicitud.
- Leer el cuerpo de la solicitud.
- Identificar el evento.
- Identificar la cuenta mediante el
Location ID.
- Identificar el contacto mediante el
Contact ID.
- Procesar la información.
- Responder correctamente a Wechatia.
La estructura básica será:
Webhook recibido
↓
Leer información
↓
Identificar evento
↓
Identificar Location ID
↓
Identificar Contact ID
↓
Procesar información
↓
Responder correctamente
4. Configurar el Webhook en Wechatia
Una vez que tuSoftware tenga preparado el endpoint, debes configurar el Webhook en Wechatia.
Ingresa a:
Configuración → Webhooks
Selecciona:
Crear Webhook
En el campo correspondiente a la URL introduce:
https://api.tuSoftware.com/webhooks/wechatia
Esta será la dirección donde Wechatia enviará los eventos.
5. Seleccionar los eventos
Un Webhook puede configurarse para determinados eventos.
Por ejemplo:
Contacto creado
Contacto actualizado
Contacto eliminado
Si tuSoftware solamente necesita recibir información cuando un contacto sea actualizado, puedes configurar únicamente:
Contacto actualizado
De esta forma, tuSoftware no recibirá eventos que no necesita procesar.
6. Ejemplo de un Webhook de contacto actualizado
Supongamos que un contacto en Wechatia tiene:
Contact ID:
abc123456789
Location ID:
ve9EPM428h8vShlRW1KT
Y el teléfono del contacto cambia.
Wechatia enviará una solicitud POST al endpoint:
https://api.tuSoftware.com/webhooks/wechatia
El cuerpo del Webhook puede contener información del evento y del contacto.
Por ejemplo:
{
"event": "contact.updated",
"locationId": "ve9EPM428h8vShlRW1KT",
"contact": {
"id": "abc123456789",
"firstName": "Juan",
"lastName": "Pérez",
"email": "juan@ejemplo.com",
"phone": "+56987654321"
}
}
7. Identificar el evento
Uno de los datos más importantes es el tipo de evento.
En el ejemplo anterior:
event:
contact.updated
Esto significa que el evento corresponde a una actualización de contacto.
TuSoftware puede utilizar este valor para determinar qué acción debe ejecutar.
Por ejemplo:
contact.created
Podría indicar:
Contacto creado
Mientras:
contact.updated
indicaría:
Contacto actualizado
Y:
contact.deleted
indicaría:
Contacto eliminado
Los eventos concretos disponibles dependerán de los eventos habilitados para la integración.
8. Identificar la cuenta mediante el Location ID
El Webhook también puede incluir el identificador de la cuenta donde ocurrió el evento.
Por ejemplo:
Location ID:
ve9EPM428h8vShlRW1KT
TuSoftware puede utilizar este valor para determinar a qué cuenta, cliente o configuración interna corresponde el evento.
Por ejemplo:
Location ID
↓
ve9EPM428h8vShlRW1KT
↓
Cuenta cliente 001
↓
Procesar evento
Esto es especialmente importante cuando tuSoftware trabaja con múltiples cuentas de Wechatia.
9. Identificar el contacto mediante Contact ID
Dentro de la información recibida estará el identificador del contacto.
Por ejemplo:
Contact ID:
abc123456789
Este identificador permite saber exactamente qué contacto generó el evento.
TuSoftware puede buscarlo en su base de datos:
Contact ID Wechatia
↓
abc123456789
↓
Usuario tuSoftware
↓
123456
De esta manera, tuSoftware puede relacionar el contacto de Wechatia con su propio usuario.
10. Guardar la relación entre IDs
Es recomendable que tuSoftware almacene la relación entre:
Usuario ID de tuSoftware
+
Contact ID de Wechatia
+
Location ID
Por ejemplo:
Usuario tuSoftware:
123456
Contact ID:
abc123456789
Location ID:
ve9EPM428h8vShlRW1KT
Esto permitirá procesar correctamente futuros Webhooks.
11. Procesar la información recibida
Supongamos que Wechatia envía:
{
"event": "contact.updated",
"locationId": "ve9EPM428h8vShlRW1KT",
"contact": {
"id": "abc123456789",
"firstName": "Juan",
"lastName": "Pérez",
"email": "juan@ejemplo.com",
"phone": "+56987654321"
}
}
TuSoftware puede procesarlo de la siguiente manera:
1. Recibir Webhook
↓
2. Detectar evento:
contact.updated
↓
3. Leer Location ID
↓
4. Leer Contact ID
↓
5. Buscar Contact ID en la base de datos
↓
6. Encontrar usuario 123456
↓
7. Actualizar información
12. Recibir campos personalizados
Los Webhooks también pueden incluir información de campos personalizados cuando corresponda.
Por ejemplo:
{
"event": "contact.updated",
"locationId": "ve9EPM428h8vShlRW1KT",
"contact": {
"id": "abc123456789",
"firstName": "Juan",
"lastName": "Pérez",
"customFields": [
{
"id": "6dvNaf7VhkQ9snc5vnjJ",
"fieldValue": "123456"
}
]
}
}
En este ejemplo:
Custom Field ID:
6dvNaf7VhkQ9snc5vnjJ
contiene:
123456
TuSoftware puede utilizar ese valor para identificar o actualizar información adicional del usuario.
13. Responder al Webhook
Después de recibir y procesar correctamente el evento, tuSoftware debe responder a la solicitud HTTP.
Por ejemplo:
200 OK
Esto indica que el Webhook fue recibido correctamente.
Conceptualmente:
Wechatia
│
│ POST
▼
tuSoftware
│
│ Procesa evento
▼
200 OK
Si tuSoftware devuelve un error, Wechatia puede interpretar que la entrega no fue procesada correctamente.
Por eso es importante que el endpoint esté preparado para responder correctamente después de procesar el evento.
14. Evitar procesar dos veces el mismo evento
En sistemas basados en Webhooks es recomendable implementar un mecanismo de idempotencia.
Esto significa que si el mismo evento llega más de una vez, tuSoftware no debe procesarlo nuevamente de manera que genere problemas.
Puedes guardar un identificador único del evento.
Por ejemplo:
Event ID:
evt_123456
TuSoftware puede almacenar:
evt_123456
Cuando llegue nuevamente:
evt_123456
puede comprobar que ya fue procesado y evitar duplicarlo.
La estructura puede ser:
Evento recibido
↓
¿Ya fue procesado?
↙ ↘
Sí No
↓ ↓
Ignorar Procesar
↓
Guardar Event ID
15. Seguridad del Webhook
El endpoint de tuSoftware estará expuesto públicamente a Internet.
Por eso debes implementar medidas de seguridad.
Como mínimo:
- Utilizar HTTPS.
- Validar las solicitudes recibidas.
- Validar el
Location ID.
- Validar la estructura del evento.
- Implementar autenticación o firma cuando esté disponible.
- No confiar automáticamente en cualquier solicitud recibida.
- Registrar los eventos procesados.
La URL debe utilizar:
https://
y no:
http://
16. Probar el Webhook
Antes de utilizarlo en producción, realiza una prueba.
Prueba 1 — Contacto creado
Crea un contacto en Wechatia.
Comprueba que tuSoftware reciba el evento.
Wechatia
↓
Webhook
↓
tuSoftware
Prueba 2 — Contacto actualizado
Modifica un contacto.
Comprueba que tuSoftware reciba:
event
Location ID
Contact ID
Datos del contacto
Prueba 3 — Identificación
Comprueba que tuSoftware pueda relacionar:
Contact ID
↓
Usuario correcto
Prueba 4 — Campos personalizados
Modifica un campo personalizado y verifica que tuSoftware reciba la información correspondiente cuando ese dato forme parte del evento.
Prueba 5 — Eventos duplicados
Envía o recibe el mismo evento más de una vez y comprueba que tuSoftware no lo procese incorrectamente.
17. Ejemplo de flujo completo
Supongamos que existe el siguiente usuario:
Usuario tuSoftware:
123456
Y está relacionado con:
Contact ID:
abc123456789
Location ID:
ve9EPM428h8vShlRW1KT
El usuario modifica su teléfono en Wechatia.
El flujo será:
Usuario modifica teléfono
↓
Wechatia detecta cambio
↓
Se genera evento
↓
Webhook
↓
https://api.tuSoftware.com/webhooks/wechatia
↓
tuSoftware recibe evento
↓
Lee Contact ID
↓
abc123456789
↓
Busca usuario relacionado
↓
Usuario 123456
↓
Actualiza información
18. Datos principales del Webhook
Durante la integración, los datos más importantes serán:
URL del Webhook
https://api.tuSoftware.com/webhooks/wechatia
Location ID
Identifica la cuenta de Wechatia:
TU_LOCATION_ID
Contact ID
Identifica el contacto:
TU_CONTACT_ID
Event
Identifica qué ocurrió:
contact.created
contact.updated
contact.deleted
Custom Field ID
Identifica un campo personalizado:
TU_CUSTOM_FIELD_ID
19. Arquitectura final
La integración quedará de esta manera:
WEBHOOK
┌──────────────────┐ ───────────────────► ┌──────────────────┐
│ │ │ │
│ Wechatia │ │ tuSoftware │
│ │ │ │
└──────────────────┘ └──────────────────┘
│ │
│ │
▼ ▼
Location ID Procesamiento
Contact ID de información
Event Usuario
Custom Fields
Resultado
Una vez configurado el Webhook, tuSoftware podrá recibir automáticamente información desde Wechatia cuando ocurran los eventos seleccionados.
El flujo será:
Wechatia
↓
Evento
↓
Webhook
↓
URL de tuSoftware
↓
Procesamiento
↓
Actualización de información
No necesitas que tuSoftware consulte constantemente a Wechatia para saber si ocurrió un cambio. El Webhook permite que Wechatia envíe la información automáticamente cuando ocurre el evento.
