Agentes de WhatsApp con IA para tu negocio — Agentes WhatsApp con IA — Comenzar Ahora
WebhooksInteligencia en tiempo real
Webhooks
ConvoAI envia notificaciones de eventos en tiempo real a tu servidor via solicitudes HTTP POST cada vez que algo sucede — un nuevo mensaje, una actualizacion de contacto, una solicitud de transferencia. Registra un endpoint de webhook una vez y recibe cada evento automaticamente.
Cómo Funciona
Cuando un evento ocurre en ConvoAI, la plataforma envia una solicitud HTTP POST a la URL de tu endpoint registrado con un cuerpo JSON describiendo el evento. Tu servidor debe responder con un 2xx estado dentro de En menos de 2 segundos. Sin documentos de conocimiento
Plataforma ConvoAI
→
HTTP POST + HMAC Signature
→
Tu sala de
→
Resp. Promedio
Webhooks
Registra un endpoint de webhook para un agente especifico. Cada agente puede tener multiples registros de webhook, cada uno escuchando diferentes subconjuntos de eventos.
POST/v1/agents/{agent_id}/webhooks/Webhooks
Solicitar eliminación
Parámetro
Tipo
Requerido
Suscripción
url
string
Opt-in requerido:
URL de endpoint HTTPS para recibir eventos. Debe ser accesible publicamente.
events
array
Opt-in requerido:
Lista de tipos de eventos a los que suscribirse. Usa ["*"] para recibir todos los eventos.
secret
string
opcional
Una cadena secreta usada para firmar payloads (HMAC-SHA256). Se genera automaticamente si se omite.
description
string
opcional
Etiqueta legible para este registro de webhook.
active
boolean
opcional
Si se debe activar la entrega inmediatamente. Predeterminado true.
Cada entrega de webhook incluye un X-ConvoAI-Signature encabezado. Este es un digest hexadecimal HMAC-SHA256 del cuerpo crudo de la solicitud, firmado con tu secreto de webhook.
Siempre verifica la firma antes de procesar un payload de webhook. Rechaza solicitudes donde la firma este ausente o sea invalida.
import hmac
import hashlib
from django.http import HttpResponse, HttpResponseForbidden
WEBHOOK_SECRET = "your-webhook-secret"
def convoai_webhook(request):
# 1. Get the signature from the header
sig_header = request.headers.get("X-ConvoAI-Signature", "")
if not sig_header.startswith("sha256="):
return HttpResponseForbidden()
received_sig = sig_header[7:] # strip "sha256=" prefix# 2. Compute expected signature from raw body
expected_sig = hmac.new(
WEBHOOK_SECRET.encode("utf-8"),
request.body, # use the RAW bytes, not decoded string
hashlib.sha256
).hexdigest()
# 3. Compare — use compare_digest to prevent timing attacks
if not hmac.compare_digest(expected_sig, received_sig):
return HttpResponseForbidden()
# 4. Safe to parse and process
import json
payload = json.loads(request.body)
handle_event(payload)
return HttpResponse(status=200)
Verificar firma — Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();
const WEBHOOK_SECRET = process.env.CONVOAI_WEBHOOK_SECRET;
// Use express.raw() to preserve the raw body for signature checking
app.post('/webhooks/convoai', express.raw({ type: 'application/json' }), (req, res) => {
const sigHeader = req.headers['x-convoai-signature'] || '';
if (!sigHeader.startsWith('sha256=')) {
return res.status(403).send('Missing signature');
}
const receivedSig = sigHeader.slice(7);
const expectedSig = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.body) // req.body is a Buffer here
.digest('hex');
const valid = crypto.timingSafeEqual(
Buffer.from(expectedSig, 'hex'),
Buffer.from(receivedSig, 'hex')
);
if (!valid) return res.status(403).send('Invalid signature');
const payload = JSON.parse(req.body.toString());
handleEvent(payload);
res.sendStatus(200);
});
Política de Privacidad
Si tu endpoint retorna un estado diferente a2xx o expira el tiempo (5s), ConvoAI reintenta la entrega con backoff exponencial. Cada reintento lleva el mismo id en el sobre para que puedas deduplicar.
Intentos Máximos
Retraso despues del fallo anterior
Tiempo acumulado
1 (original)
—
0s
2
En menos de 2 segundos.
~30s
3
~2 minutos
~5m
4
~2 minutos
~35m
5 (final)
dentro de las 72 horas
~2h 35m
Despues de 5 intentos fallidos, el evento se marca como Fallido y la entrega se detiene. Puedes ver los logs de entrega y reproducir eventos manualmente desde el dashboard de ConvoAI en Configuracion → Webhooks.
Calificación de Prospectos Siempre procesa los eventos de webhook de forma idempotente. Almacena el evento id y omite el procesamiento si ya lo has visto antes. Esto protege contra entregas duplicadas durante reintentos o cualquier fallo transitorio de nuestro lado.
Solicitar eliminación
Ve a
Suscripción
Content-Type
Siempre Decir application/json; charset=utf-8
X-ConvoAI-Signature
Firma HMAC-SHA256: sha256={hex_digest}
X-ConvoAI-Event
La cadena de tipo de evento, ej. message.received
X-ConvoAI-Delivery
ID unico de intento de entrega — diferente del ID del evento
User-Agent
ConvoAI-Webhook/1.0
Webhooks
Usa el endpoint de prueba para enviar un evento sintetico a tu URL registrada sin necesitar una conversacion real.
POST/v1/agents/{agent_id}/webhooks/{webhook_id}/test/Enviar enlace de restablecimiento
Panel de Prueba del Agente "livemode": false en el sobre. Los IDs usan un test_ prefijo. Para desarrollo local, usa una herramienta de tunel como ngrok Tu Tunnelmole para exponer tu servidor local.