Crear un endpoint de webhook

POSThttps://api.veriko.mx/v1/webhooks

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

Registra un endpoint HTTPS que recibirá los eventos suscritos. La URL debe resolver a una dirección pública: localhost y los rangos privados se rechazan.

Ese secreto verifica cada entrega: el HMAC-SHA256 del cuerpo recibido debe coincidir con la cabecera X-{Brand}-Signature: sha256=<hex>. La firma, los reintentos y la desactivación automática se describen en la arquitectura de webhooks.

Cada endpoint admite entre 1 y 10 eventos. Los validation.* generan entregas desde el momento de la suscripción; los billing.* se aceptan como suscripción válida pero todavía no producen entregas.

El número de endpoints permitido depende del rol de la cuenta. Alcanzado el tope, la creación responde webhook_limit_reached con el límite aplicado en meta.limit.

POST /v1/webhooks/{id}/test envía una entrega sintética al endpoint recién creado; conviene confirmar que el receptor responde 2xx antes de dirigirle tráfico real.

Parámetros
Parámetro	Tipo	Obligatorio	Descripción
`url`	string (uri) (?–2048)	obligatorio	URL HTTPS receptora del webhook. Debe ser HTTPS. p. ej. `https://example.com/webhooks/entregas`
`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. p. ej. `Alta de pagos en el ERP`

Petición

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/webhooks' \
  -H 'Authorization: Bearer veriko_••••' \
  -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` aparece **solo en esta respuesta** y no puede volver a consultarse: es el que verifica la firma `X-{Brand}-Signature: sha256=<hex>` que acompaña a cada entrega.
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**`POST /v1/webhooks`
Código	Clase	Descripción	Cuerpo
201	`2xx`	Endpoint creado. El campo `secret` aparece solo en esta respuesta y no puede volver a consultarse: es el que verifica la firma `X-{Brand}-Signature: sha256=<hex>` que acompaña a cada entrega.	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`
413	`4xx`	El cuerpo de la petición supera el tamaño máximo admitido (`body_too_large`).	`ErrorResponse`
422	`4xx`	La URL o la lista de eventos no superan la validación, o la cuenta alcanzó su tope de endpoints.	`ErrorResponse`
429	`4xx`	Límite de tasa excedido	`ErrorResponse`

**Errores de `POST /v1/webhooks`**
Código	Clave	Ejemplo
400	`body_empty`	El cuerpo de la petición está vacío. Envelope meta.request_id `e6f7a2b3c4d5`
400	`invalid_json`	El cuerpo no es JSON válido. Envelope meta.request_id `f7a2b3c4d5e6`
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`
422	`url_dns_failed`	No se pudo resolver el nombre de la dirección. Envelope meta.request_id `d4e5f6a1b2c4`
422	`url_ssrf_blocked`	La URL indicada resuelve a una dirección no pública. Envelope meta.request_id `d4e5f6a1b2c5`
422	`validation_error`	El campo url es obligatorio. Envelope source.pointer `/data/attributes/url` meta.request_id `b4c5d6e7f8a9`
422	`webhook_event_invalid`	El evento indicado no existe. El evento rechazado viene en meta.event. Envelope meta.request_id `c4d5e6f7a2b3`
422	`webhook_events_required`	El endpoint debe suscribirse a al menos un evento. Envelope meta.request_id `a2b3c4d5e6f7`
422	`webhook_events_too_many`	Un endpoint admite como máximo 10 eventos. Envelope meta.request_id `b3c4d5e6f7a2`
422	`webhook_limit_reached`	Se alcanzó el número máximo de endpoints permitidos. El tope aplicado viene en meta.limit. Envelope meta.request_id `d5e6f7a2b3c4`
422	`webhook_url_invalid_format`	La URL no tiene un formato válido. Envelope meta.request_id `c3d4e5f6a1b2`
422	`webhook_url_not_https`	La URL debe usar HTTPS. Envelope meta.request_id `d4e5f6a1b2c3`
422	`webhook_url_required`	El campo url es obligatorio. Envelope meta.request_id `a1b2c3d4e5f6`
422	`webhook_url_too_long`	La URL no puede exceder 2 048 caracteres. Envelope meta.request_id `b2c3d4e5f6a1`
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`).