Webhooks salientes

Un endpoint de webhook es una dirección de su lado a la que MonoPbx llama cuando ocurre algo en su empresa: empieza o termina una llamada, cambia una cola, se registra un dispositivo, llega un mensaje de texto. Cada evento que selecciona el filtro de un endpoint se envía a él como un POST JSON firmado. La entrega es al menos una vez, así que su receptor debe poder detectar que el mismo evento llegó dos veces.

Los webhooks son el único canal de automatización en esta versión.

Configurar un endpoint

1. Asegúrese de que el receptor sea accesible en una dirección https pública en el puerto 443 (u otro puerto de 1024 en adelante). Se rechazan loopback, redes privadas y nombres internos.
2. Cree el endpoint con la API (POST /api/v1/webhooks, permiso integrations:write). Elija los eventos a recibir en event_types, o déjelo vacío para todos los eventos que el endpoint puede ver.
3. Copie el secret de firma de la respuesta. Se muestra una sola vez. Si lo pierde, rótelo.
4. Presione Probar (POST /api/v1/webhooks/{id}/test). MonoPbx envía de inmediato un evento webhook.test firmado y devuelve el resultado de la entrega.

Una empresa puede tener hasta 20 endpoints. Las pruebas y los reenvíos están limitados a 10 por empresa por minuto.

Elegir los eventos

event_types acepta tipos de evento (call.ended) o patrones de tema (call.*). Se puede seleccionar cualquier tipo de evento del WebSocket de eventos, salvo los registros de auditoría. El endpoint también recibe:

• cdr.written: se guardó un registro de llamada. Los campos del registro son los de la API de registros de llamadas. No se incluyen la referencia de la grabación, el costo ni los participantes internos.
• webhook.test: solo desde el botón de prueba. No puede suscribirse a él.

Quién recibe qué

Un endpoint recibe solo los eventos que su creador puede leer en toda la empresa. El permiso para cada tipo de evento:

Eventos	Permiso
call.*, leg.*	calls:control
queue.*	queues:read
presence.*	directory:read
voicemail.*	voicemail:read
device.*	devices:read
sms.*	messaging:read
cdr.written	call_history:read
config.changed	el permiso de lectura del tipo de entrada modificada, como users:read o trunks:read
audit.*	nunca se entrega

Si crea un endpoint sin uno de estos permisos, no se le envían los eventos que lo requieren. Un filtro explícito de un evento que usted no puede recibir se rechaza, y la lista de tipos de evento solo ofrece los que puede recibir. Cambiar la URL o el filtro de un endpoint restablece su concesión a los permisos de la persona que hizo el cambio.

Verificar la firma

Cada entrega lleva estos encabezados, según la especificación de Standard Webhooks:

Encabezado	Significado
webhook-id	El id del evento. Es el mismo en cada intento y reenvío. Úselo para ignorar duplicados.
webhook-timestamp	Segundos Unix de este intento.
webhook-signature	v1,<base64>: un HMAC-SHA256 sobre {webhook-id}.{webhook-timestamp}.{body}. Durante la rotación de un secreto hay dos firmas separadas por espacios.
content-type	application/json

Use cualquier biblioteca de Standard Webhooks y pase el cuerpo crudo de la solicitud y los encabezados. La biblioteca rechaza una firma incorrecta y una marca de tiempo de más de cinco minutos.

from standardwebhooks.webhooks import Webhook

Webhook("whsec_...").verify(request.body, request.headers)  # raises if invalid or older than 5 min

import { Webhook } from "standardwebhooks";

new Webhook("whsec_...").verify(rawBody, headers);

Verifique sobre los bytes crudos del cuerpo, antes de cualquier análisis o reserialización de JSON.

Rotar el secreto

POST /api/v1/webhooks/{id}/rotate-secret devuelve un nuevo secreto, que se muestra una sola vez. El secreto anterior sigue firmando durante un periodo de gracia (24 horas por defecto, como máximo 7 días, o 0 para ninguno). Actualice su receptor durante ese periodo para que ninguna entrega sea rechazada.

Reintentos y mensajes fallidos

Una entrega se registra antes de su primer intento, así que un reinicio de MonoPbx no la pierde.

Respuesta de su receptor	Qué ocurre
Cualquier 2xx	Entregado.
Cualquier otro estado, un tiempo de espera, o un fallo de red o DNS	Se reintenta después de 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas y luego dos veces 10 horas. Un encabezado Retry-After de hasta una hora alarga la espera.
El octavo fallo	Fallida. Permanece en la vista de mensajes fallidos durante 30 días y puede reenviarse.
Una respuesta 3xx	Un fallo. Nunca se siguen redirecciones.
Una dirección bloqueada o un cuerpo mayor de 256 KiB	Fallida de inmediato.

El cuerpo de respuesta de su receptor nunca se lee ni se guarda. Para enviar de nuevo una entrega fallida, use POST /api/v1/webhooks/deliveries/{id}/redeliver; recibe ocho intentos nuevos con el mismo webhook-id.

Cada endpoint tiene un límite de frecuencia (600 entregas por minuto por defecto, hasta 6000). Las entregas por encima del límite esperan unos segundos.

Vigilar las entregas

• GET /api/v1/webhooks muestra cada endpoint con sus conteos de pendientes y fallidas.
• GET /api/v1/webhooks/deliveries?filter=status:eq:dead es la vista de mensajes fallidos.
• GET /api/v1/webhooks/deliveries/{id}/attempts muestra cada intento: hora, código de estado, latencia y resultado. Se guarda durante 90 días.

Límites

• Solo se permiten destinos https, en el puerto 443 o de 1024 en adelante. Se rechazan credenciales en la dirección.
• Se rechazan destinos en redes privadas, loopback, enlace local (incluidas las direcciones de metadatos de la nube), NAT de nivel operador y redes reservadas, tanto al guardar el endpoint como en cada intento.
• El receptor debe responder con 2xx para que la entrega cuente como exitosa.

Sobre del evento

El cuerpo de cada entrega tiene el mismo sobre: id, tenant_id, occurred_at, schema, type y data. Los JSON Schema están en el archivo docs/api/events.schema.json del repositorio del producto.