Integraciones por webhook — Zapier · Make · n8n

Excucha expone un endpoint genérico para que dispares envíos de encuestas por WhatsApp desde cualquier sistema (CRM, POS, ticketing) — sin necesidad de instalar nada.

Setup

1. Entra a Configuración → Canales → WhatsApp en tu panel de Excucha.
2. Conecta tu número de WhatsApp (escanea el QR con tu teléfono).
3. En el bloque "Webhook para integraciones" copia la URL completa. Se ve así:

https://excucha.com/api/v1/webhooks/whatsapp-send/123/aBcDeF1234567890XyZ

Esa URL contiene tu empresa_id y un secret único. No la compartas públicamente. Si crees que se filtró, usa el botón "Rotar secret" para invalidarla.

Schema del request

Método: POST Content-Type: application/json

Body:

Header opcional pero recomendado:

X-Signature: hmac_sha256(body, secret) — firma HMAC del body con tu secret. Si la incluyes, Excucha verifica que el request no fue manipulado.

Respuestas:

Zapier

1. Crea un nuevo Zap. Elige el trigger (ej. "Freshdesk → Ticket Closed").
2. Como Action elige Webhooks by Zapier → POST.
3. Configura:
   • URL: tu URL de Excucha
   • Payload Type: JSON
   • Data:
     • telefono → mapea el campo de teléfono del trigger (asegúrate que llegue en E.164)
     • encuesta_id → un valor fijo (ej. 12)
     • contacto_nombre → mapea el nombre del cliente
     • envio_id_externo → mapea el ID del ticket (para evitar duplicados si Zapier reintenta)
4. Test. Deberías ver status: queued en la respuesta.

Make (ex Integromat)

1. Nuevo escenario. Elige tu trigger (ej. "Shopify → Watch Orders").
2. Agrega módulo HTTP → Make a request.
3. Configura:
   • URL: tu URL de Excucha
   • Method: POST
   • Headers: Content-Type: application/json
   • Body type: Raw, content type JSON (application/json)
   • Request content:

     {
     "telefono": "{{1.customer.phone}}",
     "encuesta_id": 12,
     "contacto_nombre": "{{1.customer.first_name}}",
     "envio_id_externo": "shopify-{{1.id}}"
     }
     

n8n

1. Nuevo workflow. Elige tu trigger.
2. Agrega nodo HTTP Request.
3. Configura:
   • Method: POST
   • URL: tu URL de Excucha
   • Authentication: None
   • Send Body: ON, Body Content Type: JSON
   • Body Parameters:
     • telefono (expression) — ={{ $json.customer.phone }}
     • encuesta_id (number) — 12
     • contacto_nombre (expression) — ={{ $json.customer.name }}
     • envio_id_externo (expression) — ={{ $json.id }}

Con HMAC (recomendado)

Antes del nodo HTTP, agrega un nodo Crypto para firmar el body:

• Action: HMAC
• Type: SHA256
• Value: el body JSON serializado
• Secret: tu secret de Excucha

Luego en HTTP Request agrega header X-Signature: ={{ $node["Crypto"].json.hmac }}.

Ejemplos cURL

Disparo simple:

curl -X POST https://excucha.com/api/v1/webhooks/whatsapp-send/123/SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "telefono": "+573001234567",
    "encuesta_id": 12,
    "contacto_nombre": "Juan Pérez",
    "envio_id_externo": "ticket-9999"
  }'

Con HMAC (Python):

import hashlib, hmac, json, requests
secret = "tu-secret-aqui"
body = json.dumps({"telefono": "+573001234567", "encuesta_id": 12})
sig = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()
r = requests.post(
    "https://excucha.com/api/v1/webhooks/whatsapp-send/123/" + secret,
    data=body,
    headers={"Content-Type": "application/json", "X-Signature": sig}
)
print(r.status_code, r.json())

Troubleshooting

• 401 invalid_secret → revisa que copiaste la URL completa del panel; si rotaste el secret, actualiza la URL en tu integración
• 409 session_not_connected → tu WhatsApp se desconectó. Entra al panel y re-escanea el QR
• 429 monthly_limit_reached → alcanzaste el límite de tu plan; haz upgrade o espera al próximo ciclo
• Llega tarde / no llega → revisa el listado en /configuracion/canales/whatsapp (próximamente dashboard de envíos) o contacta soporte con el envio_id

Best practices

• Usa siempre envio_id_externo con un ID único de tu sistema. Esto evita duplicados si tu integración reintenta.
• Firma con HMAC en producción. El secret en la URL es necesario, pero HMAC añade integridad del payload.
• Throttle del lado tuyo si vas a disparar lotes grandes — Excucha limita a 1 msg/s por número.