Actualizar un endpoint de webhook

PUThttps://api.veriko.mx/v1/webhooks/{id}

Audiencia: public
Autenticación: API key
Permiso: webhooks:update

Actualiza la dirección receptora, los eventos suscritos o el estado de un endpoint ya registrado. Solo cambia lo que venga en el cuerpo: un campo ausente se queda como estaba, y un cuerpo sin ningún campo editable responde 422 no_valid_fields. El secreto de firma no cambia aquí. Cambiar la dirección deja el mismo secreto en el endpoint nuevo, de modo que un receptor que ya validaba firmas sigue validándolas. Para rotarlo está POST /v1/webhooks/{id}/regenerate-secret. Poner el estado en disabled detiene las entregas sin perder el historial; es lo que conviene mientras se arregla un receptor caído, en vez de borrar el endpoint y volver a crearlo.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`id`*	path	`string (uuid)`	obligatorio	UUID del endpoint de webhook. p. ej. `f47ac10b-58cc-4372-a567-0e02b2c3d479`

Parámetros
Parámetro	Tipo	Obligatorio	Descripción
`url`	string (uri) (?–2048)	opcional	URL HTTPS de destino. Reemplaza la URL anterior si se envía. p. ej. `https://example.com/webhooks/entregas`
`events`	array<string> (elementos: 1–10)	opcional	Suscripción de eventos del webhook. Reemplaza la lista anterior; máximo 10 eventos.
`description`	string \| nullanulable (?–255)	opcional	Etiqueta libre del webhook (`null` para limpiarla). p. ej. `Alta de pagos en el ERP`
`status`	string (enumeración)	opcional	Cambia el estado del webhook (`active` o `disabled`). p. ej. `active`

Petición

cURLPython•JavaScript•PHP•

curl -X PUT 'https://api.veriko.mx/v1/webhooks/{id}' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://webhook.example.com/platform",
    "events": [
      "validation.completed"
    ],
    "status": "active"
  }'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200**`WebhookEndpoint` — Endpoint actualizado.
Campo	Tipo	Descripción
`type`*	`string`	Tipo del recurso, fijo para esta operación. Forma parte de la identidad del recurso en la envoltura JSON:API. Siempre `webhook_endpoint`. p. ej. `webhook_endpoint`
`id`*	`string (uuid)`	Identificador del endpoint. p. ej. `a1b2c3d4-e5f6-7890-abcd-ef0123456789`
`attributes`*	`object`	Atributos canónicos del endpoint de webhook (URL receptora, eventos suscritos, estado y secreto).
`url`	`string (uri)`	URL HTTPS receptora. En producción se rechaza HTTP, URLs que resuelven a IPs privadas (SSRF), y URLs `>2048` caracteres. p. ej. `https://example.com/webhooks/entregas`
`events`	`array`	Lista de eventos suscritos. Máximo 10.
`description`	`string \| null`anulable	Etiqueta libre del endpoint. p. ej. `Alta de pagos en el ERP`
`status`	`string`	`active` recibe entregas. `disabled` fue apagado manualmente. `auto_disabled` fue desactivado por la plataforma tras superar `webhooks.auto_disable_threshold` fallos consecutivos. p. ej. `active`
`consecutive_failures`	`integer`	Contador de fallos consecutivos. Se resetea en éxito. p. ej. `0`
`last_delivery_at`	`TimestampUTC \| null`	Marca de tiempo UTC del último intento de entrega (cualquier status). `null` cuando el endpoint aún no recibió ningún delivery.
`secret`	`string`	Clave compartida para verificar firmas. Solo presente en la respuesta de creación y regeneración del endpoint; se omite en cualquier otra respuesta. p. ej. `whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`
`secret_hint`	`string`	Últimos 4 caracteres del secret, prefijados con `...`. Presente en cualquier respuesta donde `secret` está oculto. p. ej. `...4f2a`
`created_at`	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `_at`, `_end`, `_start`, `_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente. p. ej. `2026-05-01T05:14:38Z`
`updated_at`	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `_at`, `_end`, `_start`, `_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente. p. ej. `2026-05-01T05:14:38Z`

**Códigos de respuesta**`PUT /v1/webhooks/{id}`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Endpoint actualizado.	Sin cuerpo
400	`4xx`	El cuerpo de la petición está vacío o no es JSON válido.	`ErrorResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	`not_found` — el endpoint no existe o no pertenece al usuario.	`ErrorResponse`
413	`4xx`	El cuerpo de la petición supera el tamaño máximo admitido (`body_too_large`).	`ErrorResponse`
422	`4xx`	Datos inválidos. Códigos posibles: `webhook_url_empty`, `webhook_url_too_long`, `webhook_url_invalid_format`, `webhook_url_not_https`, `webhook_events_required`, `webhook_events_too_many`, `webhook_event_invalid`, `webhook_status_invalid`, `no_valid_fields`.	`ErrorResponse`
429	`4xx`	Límite de tasa excedido	`ErrorResponse`

**Errores de `PUT /v1/webhooks/{id}`**
Código	Clave	Ejemplo
400	`body_empty`	El cuerpo de la petición está vacío. Envelope meta.request_id `c4d5e6f7a8b9`
400	`invalid_json`	El cuerpo no es JSON válido. Envelope meta.request_id `d5e6f7a8b9c0`
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	No tienes permiso para acceder a este recurso. Envelope meta.request_id `d5e6f7a8b9c0`
413	`body_too_large`	El cuerpo de la petición es demasiado grande. Envelope meta.request_id `1a2b3c4d5e6f`
429	`rate_limit_exceeded`	Límite de peticiones excedido. Inténtalo de nuevo en 45 segundos. Envelope meta.request_id `f7a8b9c0d1e2` Cabeceras de respuesta `Retry-After`: integer — Segundos a esperar antes de reintentar. Coincide con la ventana de rate-limit del endpoint (típicamente 60s para listas, 1-5s para operaciones idempotentes en vuelo). `X-RateLimit-Limit`: integer — Límite de solicitudes configurado para este bucket (emitido sólo en 429). `X-RateLimit-Remaining`: integer — Solicitudes restantes en la ventana actual — siempre 0 en el momento del 429 (emitido sólo en 429). `X-RateLimit-Reset`: integer — Unix epoch absoluto (segundos) en que se reinicia la ventana. Emitido sólo en 429, junto con Retry-After. Puede existir sobreescritura por endpoint (p. ej. `rate_limited_login`).