Crear un endpoint de webhook

POST https://api.veriko.mx/v1/webhooks

Audiencia: public
Permiso: webhooks:create

Registra un nuevo endpoint HTTPS para recibir notificaciones de eventos. El campo secret de firma se devuelve exclusivamente en esta respuesta y no puede recuperarse después — almacénalo de forma segura. Valida con HMAC-SHA256 el cuerpo entrante contra la cabecera X-{Brand}-Signature: sha256=<hex>. Tras crear el endpoint envía una entrega sintética con POST /v1/webhooks/{id}/test para confirmar que el receptor responde 2xx antes de habilitar producción.

Parámetros
Parámetro	Tipo	Obligatorio	Descripción
`url`	string (uri) (?–2048)	obligatorio	URL HTTPS receptora del webhook. Debe ser HTTPS.
`events`	array<string> (elementos: 1–10)	obligatorio	Eventos a los que se suscribe el endpoint (1–10).
`description`	string (?–255)	opcional	Etiqueta descriptiva del endpoint.

Petición

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/webhooks' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://webhook.example.com/platform",
    "events": [
      "validation.completed",
      "validation.failed",
      "validation.error",
      "billing.payment_succeeded",
      "billing.payment_failed"
    ],
    "description": "Webhook plataforma completo"
  }'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 201** `WebhookEndpoint` — Endpoint creado. El campo `secret` solo aparece en esta respuesta; almacénalo de forma segura para verificar las firmas `X-{Brand}-Signature: sha256=<hex>` (HMAC-SHA256 sobre el cuerpo).
Campo	Tipo	Descripción
`type` *	`string`
`id` *	`string (uuid)`	Identificador del endpoint.
`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.
`events`	`array`	Lista de eventos suscritos. Máximo 10.
`description`	`string \| null` anulable	Etiqueta libre del endpoint.
`status`	`string`	`active` recibe entregas. `disabled` fue apagado manualmente. `auto_disabled` fue desactivado por la plataforma tras superar `webhooks.auto_disable_threshold` fallos consecutivos.
`consecutive_failures`	`integer`	Contador de fallos consecutivos. Se resetea en éxito.
`last_delivery_at`	`union`	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.
`secret_hint`	`string`	Últimos 4 caracteres del secret, prefijados con `...`. Presente en cualquier respuesta donde `secret` está oculto.
`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.
`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.

**Códigos de respuesta** `POST /v1/webhooks`
Código	Clase	Descripción	Cuerpo
201	`2xx`	Endpoint creado. El campo `secret` solo aparece en esta respuesta; almacénalo de forma segura para verificar las firmas `X-{Brand}-Signature: sha256=<hex>` (HMAC-SHA256 sobre el cuerpo).	Sin cuerpo
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
422	`4xx`	Datos inválidos. Códigos posibles: `webhook_url_required`, `webhook_url_too_long`, `webhook_url_invalid_format`, `webhook_url_not_https`, `webhook_events_required`, `webhook_events_too_many`, `webhook_event_invalid`, `webhook_limit_reached`.	`ErrorResponse`
429	`4xx`	Límite de tasa excedido	`ErrorResponse`

**Errores de `POST /v1/webhooks`**
Código	Clave	Detalle
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`
429	`rate_limit_exceeded`	Rate limit exceeded. Try again in 45 seconds. 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`).