watsi Webhooks

Los webhooks de watsi permiten que su sistema reciba notificaciones de eventos sin hacer sondeo. Úselos para reaccionar a nuevos mensajes entrantes, cambios en el estado de entrega y actualizaciones de conversaciones o contactos casi en tiempo real.

Conceptos clave

Suscripciones

Una suscripción de webhook le indica a watsi qué tipos de evento entregar y a qué endpoint HTTPS deben enviarse.

Eventos

Cada entrega contiene un evento JSON con un tipo, una marca de tiempo, un identificador de espacio de trabajo y un payload de datos específico del evento.

Entregas

watsi envía una entrega HTTP POST por cada evento coincidente. Las entregas se reintentan cuando el endpoint receptor falla o agota el tiempo de espera.

Firma

Cada entrega incluye una firma HMAC-SHA256 en el encabezado X-Watsi-Signature para que su servidor pueda verificar la autenticidad antes de procesar el payload.

Forma de la solicitud de entrega

watsi envía las entregas de webhook como solicitudes HTTPS POST con un cuerpo JSON. El payload específico del evento varía según el tipo de evento, pero el envelope de nivel superior se mantiene estable.

{
  "id": "evt_01HXYZ123456789",
  "type": "message.received",
  "created_at": "2025-03-15T10:30:00.000Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "message": {
      "id": "wamid.HBgL...",
      "body": "Hola"
    }
  }
}

Campo	Significado
`id`	Identificador estable del evento. Úselo para la deduplicación.
`type`	Nombre del evento legible por máquina.
`created_at`	Marca de tiempo ISO-8601 de cuándo watsi creó el evento.
`workspace_id`	Identificador del espacio de trabajo para que un mismo endpoint pueda atender a varios inquilinos.
`data`	Payload específico del evento. Consulte el catálogo de eventos para ver ejemplos.

Encabezados de entrega

Encabezado	Propósito
`X-Watsi-Signature`	HMAC-SHA256 codificado en hexadecimal del cuerpo de la solicitud sin procesar.
`X-Watsi-Event`	Tipo de evento para enrutamiento rápido, como message.received.
`X-Watsi-Delivery-Id`	Identificador único de entrega para correlación de registros y deduplicación.

Verifique siempre X-Watsi-Signature contra el cuerpo de la solicitud sin procesar antes de analizar el JSON.

Garantías de entrega

Los webhooks se entregan con una garantía de al menos una vez. Una falla transitoria de red o de aplicación puede provocar que el mismo evento se entregue más de una vez, por lo que los manejadores deben ser idempotentes.

Su endpoint debe confirmar las entregas con rapidez mediante una respuesta 2xx y trasladar el trabajo más prolongado a procesamiento en segundo plano.

Política de reintentos

watsi reintenta las entregas fallidas con un backoff creciente hasta agotar el último intento.

Intento	Notas
1	Entrega inicial
2	Reintento breve tras una falla transitoria
3	Reintento con backoff
4	Reintento con backoff más prolongado
5	Reintento final antes de marcar la entrega como fallida

Los tiempos exactos pueden evolucionar, pero las integraciones deben asumir un backoff creciente y no depender de marcas de tiempo de reintento fijas.

Seguir leyendo

Guía de firma y verificación — verifique la firma HMAC en Node.js, Python, Ruby, Go o PHP.
Catálogo de eventos — revise los tipos de evento documentados y los payloads de ejemplo.
Tutorial completo — registre una suscripción, reciba un evento y valide su firma.