Webhooks de saída — API Zyron Connect Suite

Módulo

Webhooks de salida

Configura adónde envía el Connect los eventos de tu conexión. Entrega con firma HMAC, retry con backoff y dead-letter; eventos estructurados whatsapp.message.* y whatsapp.connection.updated.

GET/webhooks/webhooks PUT/webhooks/webhooks DELETE/webhooks/webhooks GET/webhooks/deliveries/webhooks/deliveries

GET/webhooksAlcance: readOficial + Básico

Lista las configuraciones de webhook.

Una configuración por conexión. El secret se devuelve al dueño de la clave — con él se valida x-zyron-signature. structured_events lista el catálogo v2.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Campo	Tipo	Descripción
`connection_id`opcional	uuid	Filtra por conexión.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/webhooks?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Configuraciones devueltas.

Ejemplo de respuesta

{
  "data": [
    {
      "id": "5f0d5a44-1187-4f1e-a2b0-1d40c07b0e10",
      "connection_id": "<CONNECTION_ID>",
      "url": "https://seu-n8n.com/webhook/zyron",
      "events": ["whatsapp.message.received", "whatsapp.message.failed"],
      "secret": "zwh_9f2c...",
      "active": true
    }
  ],
  "structured_events": [
    "whatsapp.message.received",
    "whatsapp.message.sent",
    "whatsapp.message.delivered",
    "whatsapp.message.read",
    "whatsapp.message.failed",
    "whatsapp.connection.updated"
  ]
}

PUT/webhooksAlcance: writeOficial + Básico

Crea o actualiza el webhook de una conexión.

events vacío suscribe todo. Acepta los eventos estructurados v2 y los nombres nativos del provider. Sin secret, el Connect mantiene el actual o genera uno nuevo.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`connection_id`obligatorio	uuid	Conexión dueña del webhook.
`url`obligatorio	URL	Endpoint http(s) que recibe los eventos.
`events`opcional	string[]	Eventos suscritos. Vacío = todos.
`secret`opcional	string	Secreto del HMAC. Opcional; se genera si falta.
`active`opcional	boolean	Predeterminado true. false pausa las entregas.

Ejemplos listos

curl -X PUT "https://connect.zyronstack.com/api/v1/webhooks" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "url": "https://seu-n8n.com/webhook/zyron",
  "events": ["whatsapp.message.received", "whatsapp.message.failed"]
}'

Respuestas

201	Webhook creado.
200	Webhook actualizado.
422	URL inválida o evento no soportado.

DELETE/webhooksAlcance: writeOficial + Básico

Desactiva el webhook de una conexión.

Pausa las entregas manteniendo configuración e historial. Reactiva con PUT { active: true }.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Campo	Tipo	Descripción
`connection_id`obligatorio	uuid	Conexión del webhook.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X DELETE "https://connect.zyronstack.com/api/v1/webhooks?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Webhook desactivado.
404	Ningún webhook configurado.

GET/webhooks/deliveriesAlcance: readOficial + Básico

Historial de entregas del webhook.

Cada entrega muestra evento, estado (pending, delivered, failed, dead), intentos, último HTTP status y error.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Campo	Tipo	Descripción
`connection_id`opcional	uuid	Filtra por conexión.
`status`opcional	pending \| delivered \| failed \| dead	Filtra por el estado de la entrega.
`event`opcional	string	Filtra por el nombre del evento.
`limit`opcional	number	Cantidad de registros por página. Predeterminado 50; máximo 200 en la mayoría de listas.
`offset`opcional	number	Índice inicial de la página. Usa pagination.next_offset para la siguiente página.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/webhooks/deliveries?connection_id=<CONNECTION_ID>&status=failed" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Entregas devueltas.

Ejemplo de respuesta

{
  "data": [
    {
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "connection_id": "<CONNECTION_ID>",
      "event": "whatsapp.message.received",
      "status": "delivered",
      "attempts": 1,
      "last_status": 200,
      "last_error": null,
      "target_url": "https://seu-n8n.com/webhook/zyron",
      "delivered_at": "2026-07-14T13:28:29.120Z",
      "created_at": "2026-07-14T13:28:27.898Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 1, "next_offset": null }
}