# Alertas y webhooks

> Lee las alertas, ajusta las reglas que las crean y registra webhooks que las reciben, firmados y con reintentos.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/api/webhooks/

Para agentes: Referencia de alertas, reglas de alerta y webhooks de la API de Sypnia: tipos de alerta y umbrales, registro de webhooks, el cuerpo de una entrega, cómo verificar el encabezado Sypnia-Signature, reintentos.

Una alerta es un registro que dice que algo necesita a una persona: un problema nuevo, un problema que volvió, tu app sin responder. El motor siempre registra las alertas. Lo que pasa después depende de dónde corres:

|                                           | Motor de Sypnia (código abierto, en tu propia infraestructura)                                                  | Sypnia Cloud (servicio pago, con un plan gratis) |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| Registradas; se listan por API, MCP y CLI | Sí                                                                                                              | Sí                                               |
| Enviadas a tus webhooks                   | Sí                                                                                                              | Sí                                               |
| Correo                                    | No. El despliegue por defecto no tiene cómo enviar correos. Mira [la guía](/es/guides/alert-emails-self-hosted) | Sí                                               |
| Mostradas a las personas                  | En la Consola                                                                                                   | En la app                                        |

Las alertas se crean solo para el entorno `production`, salvo que cambies los `environments` de una regla. No hay integración con apps de chat: un webhook es la forma de enviar una alerta a cualquier otro lado.

Un motor alojado por ti también puede enviar cada alerta de cada proyecto a una URL, sin ninguna llamada a esta API: define `SYPNIA_ALERT_WEBHOOK_URL`. Mira la [referencia de configuración](https://docs.sypnia.com/es/self-hosting/configuration).

## El objeto alerta

**Campos:**

- `id` (string, opcional): `alt_…`.
- `kind` (string, opcional): Qué regla la creó. Mira las reglas de alerta.
- `title` (string, opcional): La alerta en una línea, lista para enviársela a una persona.
- `environment` (string, opcional)
- `subject` (object, opcional): De qué trata la alerta.
- `subject.type` (string): Uno de: `problem`, `uptime_check`, `page`, `api_route`, `project`.
- `subject.id` (string): El id del problema o de la comprobación, o la ruta.
- `subject.slug` (string): Solo en problemas.
- `created_at` (timestamp, opcional)
- `acknowledged_at` (timestamp o null, opcional)
- `acknowledged_by` (string o null, opcional): Quién la marcó como vista, escrito igual que `resolved_by` en un problema.
- `url` (URL, opcional): Dónde mirar, en la app o en la Consola.

## El objeto webhook

**Campos:**

- `id` (string, opcional): `whk_…`.
- `url` (URL, opcional)
- `events` (lista de string, opcional)
- `enabled` (boolean, opcional)
- `created_at` (timestamp, opcional)
- `last_delivery` (object o null, opcional): La última entrega y cómo salió.
- `disabled_reason` (string o null, opcional): `failing` cuando el motor lo apagó después de 3 días de entregas fallidas.

## Qué recibe un webhook

Cada evento es un `POST` a tu URL con un cuerpo JSON.

| Tipo de evento                | Cuándo                                                          |
| ----------------------------- | --------------------------------------------------------------- |
| `alert.created`               | Se creó una alerta. Es el que se reenvía a las personas         |
| `problem.created`             | Un problema se vio por primera vez, en cualquier entorno        |
| `problem.analyzed`            | El agente terminó un análisis. Viene en `data.problem.analysis` |
| `problem.status_changed`      | Un problema se resolvió, se reabrió, se ignoró o volvió         |
| `problem.pull_request_opened` | Solo en Sypnia Cloud: Sypnia abrió un pull request              |
| `ping`                        | Creaste el webhook, o pediste una prueba                        |

**Encabezados de una entrega:**

```http
POST /hooks/sypnia HTTP/1.1
Content-Type: application/json
User-Agent: Sypnia-Webhooks/1.0
Sypnia-Event: alert.created
Sypnia-Delivery: dlv_2s4d6f8g0h1j
Sypnia-Attempt: 1
Sypnia-Signature: t=1773306783,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

**Cuerpo de una entrega \`alert.created\`:**

```json
{
  "id": "evt_7m3n9b5v1c8x",
  "type": "alert.created",
  "created_at": "2026-03-12T09:13:02Z",
  "project": { "id": "prj_5k2m9x4q7w1z", "slug": "shop", "name": "Shop" },
  "data": {
    "alert": {
      "id": "alt_6w2e8r4t1y9u",
      "kind": "problem.new",
      "title": "New problem: 1 person tried to pay and could not.",
      "environment": "production",
      "subject": { "type": "problem", "id": "prb_8f3k2m9x4q7w", "slug": "pay-button-does-nothing" },
      "created_at": "2026-03-12T09:13:02Z",
      "acknowledged_at": null,
      "acknowledged_by": null,
      "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
    },
    "problem": {
      "id": "prb_8f3k2m9x4q7w",
      "slug": "pay-button-does-nothing",
      "status": "open",
      "title": "createPayment answered 400 in POST /api/checkout",
      "sentence": null,
      "people": 1,
      "sessions": 1,
      "first_seen": "2026-03-12T09:12:04Z",
      "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
    }
  }
}
```

**Campos de toda entrega:**

- `id` (string): El id del evento, `evt_…`. Es el mismo en cada reintento del mismo evento: guárdalo e ignora un id que ya atendiste.
- `type` (string): El tipo de evento, como en la tabla de arriba. También viene en el encabezado `Sypnia-Event`.
- `created_at` (timestamp): Cuándo ocurrió el evento, no cuándo se envió.
- `project` (object): El proyecto: `id`, `slug`, `name`.
- `data` (object): Para `alert.created`: `alert`, más `problem` o `check` cuando la alerta trata de uno. Para los tipos `problem.*`: `problem`, en la forma corta de arriba, más `previous_status` para `problem.status_changed`. Para `ping`: vacío. Una alerta enviada en los primeros 2 minutos de un problema puede traer `sentence` en `null`: la alerta no espera al agente más que eso.

## Comprueba la firma

Cualquiera que conozca tu URL le puede enviar peticiones. Comprueba que una entrega viene de Sypnia antes de actuar.

`Sypnia-Signature` trae una marca de tiempo `t` (segundos) y una firma `v1`. La firma es el HMAC-SHA256, en hexadecimal, de la marca de tiempo, un punto y el **cuerpo crudo**, con el secreto del webhook (`whsec_…`) como llave.

### 1. Toma el cuerpo crudo

Lee el cuerpo como bytes, antes de interpretar el JSON. Un cuerpo interpretado y vuelto a escribir no va a coincidir.

### 2. Calcula la firma

Calcula `HMAC-SHA256(secreto, t + "." + cuerpo crudo)` y escríbela en hexadecimal.

### 3. Compara, y revisa la hora

Compara con `v1` usando una comparación de tiempo constante. Rechaza la entrega cuando difieran, o cuando `t` esté a más de 5 minutos de tu reloj, lo que impide que alguien repita una entrega vieja.

**Node.js**

`verify.js`

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromSypnia(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}
```

**Python**

`verify.py`

```python
import hashlib, hmac, time

def is_from_sypnia(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if "t" not in parts or "v1" not in parts:
        return False
    if abs(time.time() - int(parts["t"])) > 300:
        return False

    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])
```

## Reintentos

Una entrega sale bien cuando tu receptor responde cualquier `2xx` en menos de 10 segundos. Responde primero y haz después el trabajo lento.

Cualquier otra cosa se reintenta, con el mismo id `evt_…` y un `Sypnia-Attempt` mayor:

| Intento | Cuándo             |
| ------- | ------------------ |
| 1       | De inmediato       |
| 2       | 1 minuto después   |
| 3       | 5 minutos después  |
| 4       | 30 minutos después |
| 5       | 2 horas después    |
| 6       | 6 horas después    |
| 7       | 12 horas después   |

Después de la séptima falla la entrega queda en `failed` y no se intenta más. Cuando todas las entregas a un webhook fallan durante 3 días, el motor apaga el webhook (`disabled_reason` queda en `failing`) y crea una alerta `engine.failing`. Enciéndelo otra vez con `PATCH`.

Las entregas pueden llegar en desorden y, rara vez, dos veces. Usa el `id` del evento para ignorar duplicados y `created_at` para ordenar.

## Listar alertas

`GET /v1/alerts` \[Motor, Nube]

Las alertas creadas en el rango de tiempo, la más nueva primero.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `kind` (string, opcional): Solo alertas de este tipo. Mira la lista en las reglas de alerta.
- `acknowledged` (boolean, opcional): `false` devuelve solo las alertas que nadie ha marcado como vistas.
- `since` (string, opcional, por defecto `7d`): Solo alertas creadas después de este momento.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/alerts?acknowledged=false" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "alt_6w2e8r4t1y9u",
      "kind": "problem.new",
      "title": "New problem: 1 person tried to pay and could not.",
      "environment": "production",
      "subject": {
        "type": "problem",
        "id": "prb_8f3k2m9x4q7w",
        "slug": "pay-button-does-nothing"
      },
      "created_at": "2026-03-12T09:13:02Z",
      "acknowledged_at": null,
      "acknowledged_by": null,
      "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
    }
  ],
  "next_cursor": null
}
```

## Traer una alerta

`GET /v1/alerts/{alert_id}` \[Motor, Nube]

Una alerta.

**Autenticación:** Token de API (`read`)

**Parámetros de ruta:**

- `alert_id` (string, obligatorio): El id de la alerta (`alt_…`).

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/alerts/alt_6w2e8r4t1y9u" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "id": "alt_6w2e8r4t1y9u",
  "kind": "problem.new",
  "title": "New problem: 1 person tried to pay and could not.",
  "environment": "production",
  "subject": {
    "type": "problem",
    "id": "prb_8f3k2m9x4q7w",
    "slug": "pay-button-does-nothing"
  },
  "created_at": "2026-03-12T09:13:02Z",
  "acknowledged_at": null,
  "acknowledged_by": null,
  "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
}
```

**Errores:**

- `404` `not_found`: Ninguna alerta del proyecto tiene este id.

## Marcar una alerta como vista

`POST /v1/alerts/{alert_id}/acknowledge` \[Motor, Nube]

Registra que alguien vio la alerta. No cambia nada más: el problema o la comprobación que hay detrás conserva su estado. Marcarla dos veces responde `200` y conserva la primera marca.

**Autenticación:** Token de API (`read`)

**Parámetros de ruta:**

- `alert_id` (string, obligatorio): El id de la alerta (`alt_…`).

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Petición:**

```bash
curl -X POST "https://api.sypnia.com/v1/alerts/alt_6w2e8r4t1y9u/acknowledge" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "id": "alt_6w2e8r4t1y9u",
  "kind": "problem.new",
  "title": "New problem: 1 person tried to pay and could not.",
  "environment": "production",
  "subject": {
    "type": "problem",
    "id": "prb_8f3k2m9x4q7w",
    "slug": "pay-button-does-nothing"
  },
  "created_at": "2026-03-12T09:13:02Z",
  "acknowledged_at": "2026-03-12T10:36:20Z",
  "acknowledged_by": "token:Cursor",
  "url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
}
```

**Errores:**

- `404` `not_found`: Ninguna alerta del proyecto tiene este id.

## Listar las reglas de alerta

`GET /v1/alert-rules` \[Motor, Nube]

Las reglas que crean alertas. El conjunto es fijo: hay una regla por tipo de alerta, y tú enciendes o apagas cada una y ajustas sus umbrales. No se pueden agregar tipos.

| Tipo                | Crea una alerta cuando                                                                    | Umbrales (por defecto)                    |
| ------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------- |
| `problem.new`       | Un problema se ve por primera vez                                                         | Ninguno                                   |
| `problem.regressed` | Un problema resuelto ocurre otra vez                                                      | Ninguno                                   |
| `problem.growing`   | Un problema abierto llega al doble de las personas que tenía en su última alerta          | `factor` 2, `min_people` 5                |
| `uptime.down`       | Una comprobación falla dos veces seguidas                                                 | `failures` 2                              |
| `uptime.recovered`  | Una comprobación que estaba caída vuelve a responder                                      | Ninguno                                   |
| `page.slower`       | El LCP en p75 de una página en las últimas 24 horas creció frente a los 7 días anteriores | `increase_percent` 30, `min_views` 50     |
| `api.failing`       | Una ruta de la API responde `5xx` o nada con demasiada frecuencia en la última hora       | `error_rate_percent` 2, `min_requests` 50 |
| `usage.limit`       | El proyecto llega a una parte de un límite de uso                                         | `percents` 80 y 100                       |
| `engine.failing`    | El procesamiento lleva 30 minutos atrasado, o las entregas de webhooks siguen fallando    | Ninguno                                   |

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/alert-rules" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "kind": "problem.new",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {}
    },
    {
      "kind": "problem.regressed",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {}
    },
    {
      "kind": "problem.growing",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {
        "factor": 2,
        "min_people": 5
      }
    },
    {
      "kind": "uptime.down",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {
        "failures": 2
      }
    },
    {
      "kind": "uptime.recovered",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {}
    },
    {
      "kind": "page.slower",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {
        "increase_percent": 30,
        "min_views": 50
      }
    },
    {
      "kind": "api.failing",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {
        "error_rate_percent": 2,
        "min_requests": 50
      }
    },
    {
      "kind": "usage.limit",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {
        "percents": [
          80,
          100
        ]
      }
    },
    {
      "kind": "engine.failing",
      "enabled": true,
      "environments": [
        "production"
      ],
      "thresholds": {}
    }
  ]
}
```

## Actualizar una regla de alerta

`PATCH /v1/alert-rules/{kind}` \[Motor, Nube]

Enciende o apaga una regla, cambia los entornos que vigila o cambia sus umbrales. Envía solo lo que cambia; los umbrales se mezclan clave por clave.

**Autenticación:** Token de API (`admin`)

**Parámetros de ruta:**

- `kind` (string, obligatorio): El tipo de la regla, por ejemplo `page.slower`. Uno de: `problem.new`, `problem.regressed`, `problem.growing`, `uptime.down`, `uptime.recovered`, `page.slower`, `api.failing`, `usage.limit`, `engine.failing`.

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Cuerpo:**

- `enabled` (boolean, opcional): `false` detiene este tipo de alerta.
- `environments` (lista de string, opcional): Los entornos que vigila la regla.
- `thresholds` (object, opcional): Los umbrales que cambian, por nombre. Mira la tabla de reglas.

**Petición:**

```bash
curl -X PATCH "https://api.sypnia.com/v1/alert-rules/page.slower" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"thresholds": {"increase_percent": 50}}'
```

**Respuesta (200):**

```json
{
  "kind": "page.slower",
  "enabled": true,
  "environments": [
    "production"
  ],
  "thresholds": {
    "increase_percent": 50,
    "min_views": 50
  }
}
```

**Errores:**

- `400` `invalid_request`: Un umbral no existe para este tipo o está fuera de rango. `param` lo nombra.
- `404` `not_found`: Ninguna regla tiene este tipo.

## Listar webhooks

`GET /v1/webhooks` \[Motor, Nube]

Los webhooks del proyecto. Los secretos no se muestran.

**Autenticación:** Token de API (`admin`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/webhooks" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "whk_4z6x8c2v0b1n",
      "url": "https://shop.example.com/hooks/sypnia",
      "events": [
        "alert.created",
        "problem.analyzed"
      ],
      "enabled": true,
      "created_at": "2026-02-02T09:25:00Z",
      "last_delivery": {
        "at": "2026-03-12T10:33:06Z",
        "status": "delivered",
        "response_status": 200
      },
      "disabled_reason": null
    }
  ],
  "next_cursor": null
}
```

## Crear un webhook

`POST /v1/webhooks` \[Motor, Nube]

Registra una URL tuya para recibir eventos. El secreto de firma está en `secret` y se muestra **solo en esta respuesta**. La URL debe ser `https` (un motor alojado por ti también acepta `http` cuando `SYPNIA_WEBHOOKS_ALLOW_HTTP` es `true`, para un receptor dentro de tu propia red).

El motor envía un evento `ping` apenas se crea, para que veas funcionar tu receptor.

**Autenticación:** Token de API (`admin`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Encabezados:**

- `Idempotency-Key` (string, hasta 255 caracteres, opcional): Un valor tuyo, de 1 a 255 caracteres, que hace que la llamada se pueda repetir sin riesgo. Mira [idempotencia](https://docs.sypnia.com/es/api/errors-limits-pagination#idempotency).

**Cuerpo:**

- `url` (URL, hasta 2,000 caracteres, obligatorio): A dónde enviar los eventos.
- `events` (lista de string, opcional, por defecto `['alert.created']`): Los tipos de evento que se envían. `problem.pull_request_opened` solo ocurre en Sypnia Cloud. Uno de: `alert.created`, `problem.created`, `problem.analyzed`, `problem.status_changed`, `problem.pull_request_opened`.
- `enabled` (boolean, opcional, por defecto `true`): `false` lo crea en pausa.

**Petición:**

```bash
curl -X POST "https://api.sypnia.com/v1/webhooks" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://shop.example.com/hooks/sypnia", "events": ["alert.created", "problem.analyzed"]}'
```

**Respuesta (201):**

```json
{
  "id": "whk_4z6x8c2v0b1n",
  "url": "https://shop.example.com/hooks/sypnia",
  "events": [
    "alert.created",
    "problem.analyzed"
  ],
  "enabled": true,
  "secret": "whsec_Jt5nQ8rV2xZ7cB4mK9pL1dF6hS3gA0wE",
  "created_at": "2026-02-02T09:25:00Z",
  "last_delivery": null,
  "disabled_reason": null
}
```

**Errores:**

- `400` `invalid_request`: La URL no es `https`, resuelve a una dirección privada (Sypnia Cloud), o `events` tiene un tipo desconocido.
- `409` `limit_reached`: El proyecto ya tiene 10 webhooks.

## Traer un webhook

`GET /v1/webhooks/{webhook_id}` \[Motor, Nube]

Un webhook, sin su secreto.

**Autenticación:** Token de API (`admin`)

**Parámetros de ruta:**

- `webhook_id` (string, obligatorio): El id del webhook (`whk_…`).

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Respuesta (200):**

```json
{
  "id": "whk_4z6x8c2v0b1n",
  "url": "https://shop.example.com/hooks/sypnia",
  "events": [
    "alert.created",
    "problem.analyzed"
  ],
  "enabled": true,
  "created_at": "2026-02-02T09:25:00Z",
  "last_delivery": {
    "at": "2026-03-12T10:33:06Z",
    "status": "delivered",
    "response_status": 200
  },
  "disabled_reason": null
}
```

**Errores:**

- `404` `not_found`: Ningún webhook del proyecto tiene este id.

## Actualizar un webhook

`PATCH /v1/webhooks/{webhook_id}` \[Motor, Nube]

Cambia la URL, los eventos o `enabled`. Poner `enabled` en `true` en un webhook que el motor apagó reanuda las entregas. Envía `rotate_secret` en `true` para recibir un secreto nuevo, que se muestra solo en esta respuesta; el anterior deja de funcionar de inmediato.

**Autenticación:** Token de API (`admin`)

**Parámetros de ruta:**

- `webhook_id` (string, obligatorio): El id del webhook (`whk_…`).

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Cuerpo:**

- `url` (URL, hasta 2,000 caracteres, opcional): A dónde enviar los eventos.
- `events` (lista de string, opcional): Los tipos de evento que se envían. Reemplaza la lista.
- `enabled` (boolean, opcional): `false` pausa las entregas; los eventos que ocurran mientras tanto no se envían después.
- `rotate_secret` (boolean, opcional, por defecto `false`): `true` reemplaza el secreto de firma.

**Petición:**

```bash
curl -X PATCH "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"events": ["alert.created"]}'
```

**Respuesta (200):**

```json
{
  "id": "whk_4z6x8c2v0b1n",
  "url": "https://shop.example.com/hooks/sypnia",
  "events": [
    "alert.created"
  ],
  "enabled": true,
  "created_at": "2026-02-02T09:25:00Z",
  "last_delivery": {
    "at": "2026-03-12T10:33:06Z",
    "status": "delivered",
    "response_status": 200
  },
  "disabled_reason": null
}
```

**Errores:**

- `404` `not_found`: Ningún webhook del proyecto tiene este id.

## Borrar un webhook

`DELETE /v1/webhooks/{webhook_id}` \[Motor, Nube]

Borra el webhook y detiene sus entregas pendientes.

**Autenticación:** Token de API (`admin`)

**Parámetros de ruta:**

- `webhook_id` (string, obligatorio): El id del webhook (`whk_…`).

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Petición:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Errores:**

- `404` `not_found`: Ningún webhook del proyecto tiene este id.

## Listar las entregas de un webhook

`GET /v1/webhooks/{webhook_id}/deliveries` \[Motor, Nube]

Lo que se le envió al webhook y cómo respondió tu receptor, lo más nuevo primero. Las entregas se guardan 30 días. Sirve para saber por qué no llegó una alerta.

**Autenticación:** Token de API (`admin`)

**Parámetros de ruta:**

- `webhook_id` (string, obligatorio): El id del webhook (`whk_…`).

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `status` (string, opcional): Solo entregas en este estado. Uno de: `pending`, `delivered`, `failed`.
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n/deliveries?status=failed" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "dlv_2s4d6f8g0h1j",
      "event_id": "evt_7m3n9b5v1c8x",
      "event_type": "alert.created",
      "status": "delivered",
      "attempts": 1,
      "response_status": 200,
      "response_ms": 142,
      "created_at": "2026-03-12T09:13:03Z",
      "delivered_at": "2026-03-12T09:13:03Z",
      "next_attempt_at": null,
      "error": null
    }
  ],
  "next_cursor": null
}
```

**Errores:**

- `404` `not_found`: Ningún webhook del proyecto tiene este id.

## Enviar un evento de prueba

`POST /v1/webhooks/{webhook_id}/test` \[Motor, Nube]

Le envía ahora un evento `ping` al webhook, firmado como uno real, y responde con lo que dijo tu receptor. No se reintenta y no se guarda como entrega.

**Autenticación:** Token de API (`admin`)

**Parámetros de ruta:**

- `webhook_id` (string, obligatorio): El id del webhook (`whk_…`).

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Petición:**

```bash
curl -X POST "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n/test" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Respuesta (200):**

```json
{
  "ok": true,
  "response_status": 200,
  "response_ms": 131,
  "error": null
}
```

**Errores:**

- `404` `not_found`: Ningún webhook del proyecto tiene este id.

Los errores que cualquier endpoint puede responder (`401`, `403`, `429`, `500`, `503`) están en [Errores, límites, paginación](https://docs.sypnia.com/es/api/errors-limits-pagination).
