---
title: "Webhooks"
description: "Suscríbase a eventos implementados de usuarios, organizaciones, membresías, invitaciones y certificados SAML a través de entregas HTTP firmadas."
locale: "es"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/es/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

## Nomenclatura de eventos

Los eventos implementados siguen el patrón `<object>.<action>`. El header vonvon-webhook-event y el type del body contienen el nombre exacto del evento; cada entrega también tiene un `svix-id` único.

| Objeto | Acciones |
| --- | --- |
| `user` | created, updated, deleted, restored, banned, unbanned, deactivated |
| `organization` | created, updated, deleted, restored |
| `organization.auth_policy` | actualizado |
| `organization.delivery_channels` | actualizado |
| `organization.social_providers` | actualizado |
| `organization.outbound_saml_app` | created, deleted |
| `organization.scim_target` | created, deleted |
| `organizationMembership` | created, updated, deleted, restored |
| `organizationInvitation` | created, accepted, revoked |
| `connection` | saml\_certificate\_renewed |
| `user.*` | Comodín de suscripción para todos los eventos de usuario implementados. |
| `organization.*` | Comodín de suscripción para todos los eventos de la organización implementados, incluidos los subeventos punteados. |
| `organizationMembership.*` | Comodín de suscripción para todos los eventos de membresía de organizaciones implementados. |
| `*` | Comodín de suscripción para cada evento implementado. |

## Estructura del payload

Cada entrega de webhook es un HTTP POST con `Content-Type: application/json`. El cuerpo contiene el evento exacto `type` y su `data`; Los metadatos svix se incluyen en los encabezados de solicitud.

```json
{
  "type": "user.created",
  "data": {
"userId": "user_01abc"
  }
}
```

## Verificación de firma

Vonvon firma cada entrega con HMAC-SHA256. Verifica la firma antes de procesar el payload. Rechaza entregas con más de 5 minutos de antigüedad para prevenir ataques de reproducción.

| Encabezado | Descripción |
| --- | --- |
| `svix-id` | ID de mensaje único. Úsalo para deduplicar entregas reintentadas. |
| `svix-timestamp` | Segundos Unix cuando se envió el mensaje. |
| `svix-signature` | El encabezado svix-signature comienza con el prefijo literal v1, seguido del HMAC-SHA256 codificado con Base64 de `${svix-id}.${svix-timestamp}.${raw-body}` utilizando el secreto de firma del punto final. |

```ts
import { verifyWebhook } from '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_WEBHOOK_SECRET,
})
if (!result.ok) {
  return new Response('Invalid webhook', { status: 400 })
}
const { type, data } = result.value.payload
```

## Reintentos y mensajes fallidos

- Los intentos de entrega usan retroceso exponencial y terminan con el estado dead. Cuando se agota la cola, el mensaje original se conserva cifrado como registro no entregado para que un Instance Manager pueda inspeccionarlo y reenviarlo.
- La entrega está desacoplada de la ruta de autenticación mediante Cloudflare Queues. Un endpoint lento o no disponible no afecta la latencia de inicio de sesión.
- Usa el encabezado `svix-id` para deduplicar entregas en tu lado. Los reintentos llevan el mismo `svix-id` que el intento original.

```mermaid
flowchart LR
  Vonvon --> Queue
  Queue -->|HTTPS| Endpoint
  Endpoint -->|2xx| ACK
  Endpoint -->|non-2xx| Retry
  Retry --> Queue
  Retry -->|max_retries| dlq["D1 DLQ"]
```

## Recuperación del endpoint

Utilice `POST /v1/webhooks/:id/restore` para reactivar un punto final eliminado y `POST /v1/webhooks/:id/rotate-secret` para reemplazar su secreto de firma. El nuevo `signing_secret` se devuelve una vez. La reproducción a nivel de producto por ID de entrega o `time range` no está implementada.

```shell
curl -X POST https://vonvon.id/v1/webhooks/webhook_xxx/rotate-secret \
  -H 'Authorization: Bearer sk_live_xxx'
```

## Límite del historial de entrega

Vonvon no expone una Events API de consulta. Usa `GET /v1/webhooks` para gestionar las suscripciones. El estado de entrega y el reenvío desde la cola de mensajes no entregados son superficies operativas para Instance Managers, no un flujo de eventos del tenant.

```shell
curl 'https://vonvon.id/v1/webhooks?limit=100' \
  -H 'Authorization: Bearer sk_live_xxx'
```

Source: https://vonvon.id/es/webhooks/index.mdx