Configurar Webhooks

Reciba notificaciones en tiempo real sobre mensajes entrantes, actualizaciones de estado de entrega y otros eventos en su aplicación.

conversation.created — Nueva conversación

conversation.closed — Conversación cerrada

Ocurre un evento (por ejemplo, mensaje recibido)

Si no hay 200, reintentamos con retroceso exponencial

Eventos: Seleccione qué eventos desea recibir

ID único del evento (usar para deduplicación)

Cadena de tipo de evento (p. ej., message.received)

Marca de tiempo ISO 8601 de cuando ocurrió el evento

Payload específico del evento (varía según el tipo de evento)

El array attachments solo está presente cuando el mensaje incluye archivos multimedia. Cada adjunto incluye un id único, content_type, file_size y dos URLs de descarga. Tipos admitidos: image, video, audio, document, sticker.

url: Endpoint de API estable. Requiere autenticación (API key o token de sesión). Nunca expira.

signed_url: URL pre-firmada de GCS. No requiere autenticación. Expira después de 24 horas.

Si la descarga multimedia de la plataforma falla, los datos sin procesar de la plataforma se pasan con un marcador "source": "platform" en lugar de los campos enriquecidos. Los tipos que no son archivos (ubicación, contactos, reacciones) no se ven afectados.

Cada evento que incluye un objeto de contacto también lleva un array contact_methods[] con todos los identificadores del contacto (el principal primero). Los campos phone y email de nivel superior se conservan por compatibilidad con versiones anteriores.

Las selecciones de respuesta rápida y de lista llegan como message_type "button". El texto está en "text" y un objeto "meta.button" estructurado contiene el id y el payload, lo que permite enrutar la selección sin analizar el texto.

Mostrar ejemplo con clic en botón (respuesta rápida / lista)

Identificador estable del botón tal como se definió al enviar el mensaje.

Payload devuelto por el canal (coincide con el id para respuestas rápidas).

Texto legible que el usuario vio y seleccionó.

Los mensajes salientes que incluyen archivos adjuntos contienen el mismo esquema enriquecido de adjuntos (id, url, signed_url, content_type, file_size) que los mensajes entrantes.

El campo error está a nivel de datos (no dentro de message.meta). Los objetos conversation y contact completos también se incluyen.

Los eventos de actualización de estado (delivered, read) usan un objeto conversation más simple sin bot_session_id ni campos de marca de tiempo last_*_at. El objeto contact_method no se incluye.

Los objetos de conversación de email incluyen campos adicionales: email_integration_id y email_thread_id para el contexto de hilos.

El evento reopened incluye menos campos de conversación que otros eventos de conversación (sin bot_session_id, marcas de tiempo last_*_at ni subject).

contact.updated y contact.deleted usan la misma estructura. El campo type del evento distingue entre ellos.

Obtenga el cuerpo de la solicitud sin procesar (antes de analizar JSON)

Calcule HMAC-SHA256 usando su secreto de webhook

Compare con el encabezado X-SendSeven-Signature

Use comparación de tiempo seguro para prevenir ataques de temporización

Su URL sea accesible públicamente (no localhost)

Su certificado SSL sea válido (no autofirmado)

No haya un firewall bloqueando las IPs de SendSeven

Usando JSON analizado en lugar del cuerpo sin procesar

Secreto de webhook incorrecto (copie nuevamente desde configuración)

Middleware modificando el cuerpo de la solicitud

Problemas de codificación (asegúrese de usar UTF-8)

Almacene el ID del evento y verifique duplicados antes de procesar

Haga que sus manejadores de eventos sean idempotentes

Responda con 200 lo más rápido posible (procese de forma asíncrona)

Los Webhooks son callbacks HTTP que SendSeven utiliza para enviar eventos en tiempo real a su aplicación. En lugar de consultar la REST API periódicamente, su endpoint recibe notificaciones instantáneas cuando ocurre algo importante: llega un mensaje, se cierra una conversación, se crea un contacto o cambia el estado de entrega. Cada solicitud de webhook está firmada con HMAC por seguridad y se reintenta automáticamente en caso de fallo con retroceso exponencial, garantizando que ningún evento se pierda.

Una cuenta de SendSeven con al menos un canal conectado

Un endpoint HTTPS público que pueda recibir solicitudes HTTP POST

Un certificado SSL válido (Let's Encrypt funciona perfectamente)

Conocimientos básicos de REST API y JSON

Página de Webhooks en el panel de SendSeven con el botón Agregar endpoint resaltado

Diálogo Agregar endpoint con campo de URL HTTPS y suscripciones de eventos en SendSeven

Eventos: Seleccione los eventos que desea recibir

Encabezado Authorization (opcional): Encabezado de autenticación personalizado enviado con cada entrega

A través de la API también puede configurar: retry_strategy (exponential/linear/none), max_retries (predeterminado 8, máx. 15) y timeout_seconds (predeterminado 30, rango 5–60)

Ventana emergente de Webhook creado correctamente mostrando la clave secreta con un botón Copiar

Página de detalle del webhook mostrando la URL del endpoint, eventos suscritos, historial de entregas y estado de salud en SendSeven

Automáticamente al crear un webhook desde el panel

Automáticamente al crear un webhook vía la API (POST /api/v1/webhook-endpoints)

Automáticamente cuando se actualiza la URL del webhook

Bajo demanda mediante el endpoint de verificación (POST /api/v1/webhook-endpoints/{id}/verify)

1. Crear un endpoint de webhook
2. Registrar el webhook en SendSeven
3. Seleccionar los tipos de eventos a recibir
4. Gestionar el desafío de verificación del webhook
5. Verificar la firma del webhook
6. Gestionar los eventos entrantes
7. Probar con eventos de ejemplo