> ## Documentation Index
> Fetch the complete documentation index at: https://developers.flowestate.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Suscripciones a webhooks

> Lista los eventos soportados y gestiona destinos de suscripción programáticamente.

Esta página cubre el API de **gestión** de suscripciones a webhooks. Para el formato de las entregas entrantes (headers, firmas, política de reintentos) ver la [guía de Webhooks](/es/webhooks).

***

## Listar tipos de eventos

```http theme={null}
GET /webhooks/events
```

**Scope:** `webhooks:manage`. Devuelve la lista completa de tipos de eventos a los que puedes suscribirte, más una agrupación de UI.

### Response 200

```json theme={null}
{
  "events": [
    "lead.created", "lead.updated", "lead.stage_changed",
    "lead.assigned", "lead.unassigned",
    "lead.won", "lead.lost", "lead.deleted",
    "lead.note_added", "lead.communication_logged",
    "project.created", "project.updated", "project.deleted",
    "unit.created", "unit.updated", "unit.status_changed"
  ],
  "groups": {
    "Leads": ["lead.created", "lead.updated", "lead.stage_changed", "lead.assigned", "lead.unassigned", "lead.won", "lead.lost", "lead.deleted", "lead.note_added", "lead.communication_logged"],
    "Projects": ["project.created", "project.updated", "project.deleted"],
    "Units": ["unit.created", "unit.updated", "unit.status_changed"]
  }
}
```

Usa el objeto `groups` para construir un dropdown ordenado en tu UI de integración. El array `events` es la lista plana para validación.

***

## Listar suscripciones

```http theme={null}
GET /webhooks/subscriptions
```

**Scope:** `webhooks:manage`. Lista las suscripciones gestionadas por el cliente que llama (solo integraciones Zapier / Make / API — las suscripciones gestionadas desde el panel quedan exclusivamente bajo el panel).

### Response 200

```json theme={null}
{
  "data": [
    {
      "id": "wh_...",
      "target_url": "https://hook.example.com/incoming",
      "events": ["lead.created"],
      "external_id": "make-scenario-42",
      "managed_by": "make",
      "is_active": true,
      "created_at": "2026-04-29T18:04:15.000Z"
    }
  ]
}
```

***

## Crear una suscripción

```http theme={null}
POST /webhooks/subscriptions
```

**Scope:** `webhooks:manage`.

### Request body

```json theme={null}
{
  "target_url": "https://hook.example.com/incoming",
  "event": "lead.created",
  "external_id": "make-scenario-42",
  "name": "Make: leads nuevos"
}
```

| Campo         | Requerido | Notas                                                                 |
| ------------- | --------- | --------------------------------------------------------------------- |
| `target_url`  | sí        | URL HTTPS para recibir los eventos.                                   |
| `event`       | sí        | Un solo [tipo de evento](/es/enums#webhookeventtype) por suscripción. |
| `external_id` | no        | Muy recomendado. Ver nota de idempotencia abajo.                      |
| `name`        | no        | Etiqueta humana, ≤ 255 caracteres.                                    |

<Tip>**Pasa siempre `external_id`** cuando puedas — típicamente es el ID del scenario / zap / flow de tu lado. Si la suscripción ya existe para ese `external_id`, la llamada es idempotente y devuelve `200` con el registro existente en lugar de `409`. Esto es lo que hace seguros los reintentos de Make / Zapier ante replays.</Tip>

### Response 201 (suscripción nueva)

```json theme={null}
{
  "id": "wh_...",
  "target_url": "https://hook.example.com/incoming",
  "event": "lead.created",
  "external_id": "make-scenario-42",
  "managed_by": "make",
  "secret": "<secret hex>",
  "supported_events": ["lead.created", "..."]
}
```

<Warning>El `secret` se devuelve **solo al momento de la creación**. Guárdalo — lo necesitas para verificar las firmas de los webhooks (ver [Verificar la firma](/es/webhooks#verificar-la-firma)). Si lo pierdes, elimina la suscripción y crea una nueva.</Warning>

### Response 200 (replay idempotente)

Cuando el `external_id` ya existe para este cliente, recibes la suscripción existente con el mismo body **pero sin `secret`**. Tu secret guardado de la creación original sigue siendo válido.

### Errores

* `403 FORBIDDEN` — falta el scope `webhooks:manage`, o se alcanzó el límite del plan para webhook endpoints.

***

## Obtener una suscripción

```http theme={null}
GET /webhooks/subscriptions/{id}
```

**Scope:** `webhooks:manage`. Suscripción individual.

***

## Eliminar una suscripción

```http theme={null}
DELETE /webhooks/subscriptions/{id}
```

**Scope:** `webhooks:manage`. Borrado duro de las suscripciones de plataformas externas.

<Warning>Las suscripciones gestionadas desde el panel solo se pueden borrar desde la UI de FlowEstate — el API devuelve `403` para esos casos. Esto protege a los usuarios de que conectores de terceros eliminen accidentalmente suscripciones que no crearon.</Warning>

### Response 200

```json theme={null}
{ "id": "wh_...", "deleted": true }
```