Configurar Webhooks

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

Ocurre un evento (por ejemplo, mensaje recibido)

Si no hay 200, reintentamos con retroceso exponencial

Eventos: Seleccione qué eventos desea recibir

ID unico del evento (usar para deduplicacion)

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

Marca de tiempo ISO 8601 de cuando ocurrio el evento

Payload especifico del evento (varia segun el tipo de evento)

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

url: Endpoint de API estable. Requiere autenticacion (API key o token de sesion). Nunca expira.

signed_url: URL pre-firmada de GCS. No requiere autenticacion. Expira despues 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 (ubicacion, contactos, reacciones) no se ven afectados.

Cada evento que incluye un objeto de contacto tambien 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 rapida y de lista llegan como message_type "button". El texto esta en "text" y un objeto "meta.button" estructurado contiene el id y el payload, lo que permite enrutar la seleccion sin analizar el texto.

Mostrar ejemplo con clic en boton (respuesta rapida / lista)

Identificador estable del boton tal como se definio al enviar el mensaje.

Payload devuelto por el canal (coincide con el id para respuestas rapidas).

Texto legible que el usuario vio y selecciono.

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 esta a nivel de datos (no dentro de message.meta). Los objetos conversation y contact completos tambien se incluyen.

Los eventos de actualizacion de estado (delivered, read) usan un objeto conversation mas simple sin bot_session_id ni campos de marca de tiempo last_*_at. El objeto contact_method no se incluye.

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

El evento reopened incluye menos campos de conversacion que otros eventos de conversacion (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 aplicacion. En lugar de consultar la REST API periodicamente, su endpoint recibe notificaciones instantaneas cuando ocurre algo importante: llega un mensaje, se cierra una conversacion, se crea un contacto o cambia el estado de entrega. Cada solicitud de webhook esta firmada con HMAC por seguridad y se reintenta automaticamente en caso de fallo con retroceso exponencial, garantizando que ningun evento se pierda.

Una cuenta de SendSeven con al menos un canal conectado

Un endpoint HTTPS publico que pueda recibir solicitudes HTTP POST

Un certificado SSL valido (Let's Encrypt funciona perfectamente)

Conocimientos basicos de REST API y JSON

Pagina de Webhooks en el panel de SendSeven con el boton Agregar endpoint resaltado

Dialogo Agregar endpoint con campo de URL HTTPS y suscripciones de eventos en SendSeven

Eventos: Seleccione los eventos que desea recibir

Ventana emergente de Webhook creado correctamente mostrando la clave secreta con un boton Copiar

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

Automaticamente al crear un webhook desde el panel

Automaticamente al crear un webhook via la API (POST /api/v1/webhook-endpoints)

Automaticamente cuando se actualiza la URL del webhook

Bajo demanda mediante el endpoint de verificacion (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